# Tell Class::DBI a little about yourself.
Film->table('Movies');
Film->columns('All', qw( Title Director Rating NumExplodingSheep ));
Film->columns('Primary', 'Title');
Film->set_db('Main', 'dbi:mysql', 'me', 'noneofyourgoddamnedbusiness');
#-- Meanwhile, in a nearby piece of code! --#
use Film;
# Create a new film entry for Bad Taste.
$btaste = Film->new({ Title => 'Bad Taste',
Director => 'Peter Jackson',
Rating => 'R',
NumExplodingSheep => 1
});
# Retrieve the 'Gone With The Wind' entry from the database.
my $gone = Film->retrieve('Gone With The Wind');
# Shocking new footage found reveals bizarre Scarlet/sheep scene!
$gone->NumExplodingSheep(5);
$gone->Rating('NC-17');
$gone->commit;
# Grab the 'Bladerunner' entry.
my $blrunner = Film->retrieve('Bladerunner');
# Make a copy of 'Bladerunner' and create an entry of the director's
# cut from it.
my $blrunner_dc = $blrunner->copy("Bladerunner: Director's Cut");
# Ishtar doesn't deserve an entry anymore.
Film->retrieve('Ishtar')->delete;
# Find all films which have a rating of PG.
@films = Film->search('Rating', 'PG');
# Find all films which were directed by Bob
@films = Film->search_like('Director', 'Bob %');
DESCRIPTION
I hate SQL. You hate SQL. We all hate SQL. Alas, we
often find the need to make our objects persistant and
like it or not an SQL database is usually the most
flexible solution.
This module is for setting up a reasonably efficient,
reasonably simple, reasonably extendable persistant object
with as little SQL and DBI knowledge as possible.
Its uses a scheme to automatically set up accessors for
each data field in your class. These accessors control
access to the underlying database.
How to set it up
Here's a fairly quick set of steps on how to make your
class persistant. More details about individual methods
will follow.
Set up a database.
You must have an existing database set up, have DBI.pm
installed and the necessary DBD:: driver module for
that database. See the DBI manpage and the
documentation of your particular database for details.
Set up a table for your objects to be stored in.
Class::DBI works on a simple one class/one table
model. It is your responsibility to set up that
table, automating the process would introduce too many
complications (unless somebody wants to convince me
otherwise).
Using our Film example, you might declare a table
something like this:
CREATE TABLE Movies (
Title VARCHAR(255) PRIMARY KEY,
Director VARCHAR(80),
Rating CHAR(5), /* to fit at least 'NC-17' */
NumExplodingSheep INTEGER
)
Inherit from Class::DBI.
It is prefered that you use base.pm to do this rather
than appending directly to @ISA as your class may have
to inherit some protected data fields from Class::DBI
and this is important if you're using pseudohashes.
package Film;
use base qw(Class::DBI);
Declare your columns.
This can be done using columns(). The names of your
fields should match the columns in your database, one
to one. Class::DBI (via Class::Accessor) will use
this information to determine how to create accessors.
Film->columns('All', qw( Title Director Rating NumExplodingSheep ));
For more information about how you can more
efficiently declare your columns, the section on Lazy
Population of Columns
Declare the name of your table
Inform Class::DBI what table you will be storing your
objects in. This is the table you set up eariler.
Film->table('Movies');
Declare which field is your primary key
One of your fields must be a unique identifier for
each object. This will be the primary key in your
database. Class::DBI needs this piece of information
in order to construct the proper SQL statements to
access your stored objects.
Film->columns('Primary', 'Title');
Declare a database connection
Class::DBI needs to know how to access the database.
It does this through a DBI connection which you set
up. Set up is by calling the set_db() method and
declaring a database connection named 'Main'.
set_db() is inherited from Ima::DBI. See that
module's man page for details.
XXX I should probably make this even simpler.
set_db_main() or something.
Done.
All set! You can now use the constructors (new(),
copy() and retrieve()) destructors (delete()) and all
the accessors and other garbage provided by
Class::DBI. Make some new objects and muck around a
bit. Watch the table in your database as your object
does its thing and see things being stored, changed
and deleted.
Is it not nifty? Worship the module.
WHAT IS THIS?
This is Class::DBI, a perl module.
HOW DO I INSTALL IT?
To install this module, cd to the directory that contains this README
file and type the following:
perl Makefile.PL
make test
make install
To install this module into a specific directory, do:
perl Makefile.PL PREFIX=/name/of/the/directory
...the rest is the same...
Please also read the perlmodinstall man page, if available.
WHAT ELSE DO I NEED?
You need these other Perl modules...
Carp::Assert 0.06 or higher
Class::Accessor 0.10 or higher
Class::Data::Inheritable 0.02 or higher
Ima::DBI 0.20 or higher
Class::Fields 0.08 or higher
