NAME Class::DBI - Simple Object Persistance SYNOPSIS package Film; use base qw(Class::DBI); # 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'. Film->set_db('Main', 'dbi:mysql', 'user', 'password'); 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