NAME

Class::DBI::AutoLoader - Generates Class::DBI subclasses dynamically.

SYNOPSIS

  use Class::DBI::AutoLoader (
        dsn       => 'dbi:mysql:database',
        username  => 'username',
        password  => 'passw0rd',
        options   => { RaiseError => 1 },
        tables    => ['favorite_films','directors']
        namespace => 'Films'
  );
  
  my $film = Films::FavoriteFilms->retrieve(1);
  my $dir  = Films::Directors( film => $film->id() );

DESCRIPTION

Class::DBI::AutoLoader scans the tables in a given database, and auto-generates the Class::DBI classes. These are loaded into your package when you import Class::DBI::AutoLoader, as though you had created the Data::FavoriteFilms class and "use"d that directly.

NOTE

Class::DBI::AutoLoader messes with your table names to make them look more like regular class names. Specifically it turns table_name into TableName. The actual function is just:

 $table = join('', map { ucfirst($_) } split(/[^a-zA-Z0-9]/, $table));

WARNING

I haven't tested this with any database but MySQL. Let me know if you use it with PostgreSQL or SQLite. Success or failure.

OPTIONS

Options that can be used in the import:

dsn
The standard DBI style DSN that you always pass.
username
The username for the database.
password
The password for the database.
options
A hashref of options such as you'd pass to the DBI->connect() method. This can contain any option that is valid for your database.
tables
An array reference of table names to load. If you leave this option out, all tables in the database will be loaded.
namespace
The master namespace you would like your packages declared in. See the example above.
use_base
If you don't specify a base class, then Class::DBI::BaseDSN will be used. This module does explicitly use the method 'set_up_table' from the Class::DBI::mysql, Class::DBI::Pg, and Class::DBI::SQLite series of modules. Unless you have a module that supports, or subclasses, these than you won't want to use this.
additional_packages
An array reference of additional packages you would like each class to "use". For example:
```
 use Class::DBI::AutoLoader (
        ...
        additional_packages => ['Class::DBI::AbstractSearch']
 );
    
```
This allows you to use Class::DBI plugins or other assorted goodies in the generated class.

SUPPORTED DATABASES

Currently this module supports MySQL, PostgreSQL, and SQLite via Class::DBI::mysql, Class::DBI::Pg, and Class::DBI::SQLite.

TIPS AND TRICKS

USE ADDITIONAL_PACKAGES

Class::DBI::AbstractSearch is extremely useful for doing any kind of complex query. Use it like this:

 use Class::DBI::AutoLoader (
        ...
        additional_packages => ['Class::DBI::AbstractSearch']
 );
 
 my @records = MyDBI::Table->search_where( fname => ['me','you','another'] );

Please see Class::DBI::AbstractSearch for full details

USE IN MOD_PERL

Put your use Class::DBI::AutoLoader(...) call in your startup.pl file. Then all your mod_perl packages can use the generated classes directly.

USE IN CGIs

If you don't use the "tables" option and you don't need all of the tables in the database, you're going to take an unneccessary penalty.

WRAP IT IN A SUBCLASS

You probably want to wrap this in a subclass so you don't have to go through all of the dsn, user, blah blah everytime you use it. Additionally, you can put any __PACKAGE__->set_sql(...) type stuff in your subclass. That's helpful since you can't edit the generated classes.

USING A SUBCLASS FOR CGIs

 package My::DBI::ForCGI;
 
 sub import {
     my ($self,@tables) = @_;
     require Class::DBI::AutoLoader;
     Class::DBI::AutoLoader->import(
         dsn => 'dbi:mysql:application',
                 username => 'joe',
                 password => 'friday',
                 options => { RaiseError => 1 },
                 tables => \@tables,
                 namespace => 'My::DBI::ForCGI'
     );
 }
 1;

Then in your CGI:

 use strict;
 use CGI;
 use My::DBI::ForCGI ( tables => 'users' );
 my $cgi = CGI->new();
 my $user = My::DBI::ForCGI::Users->retrieve( $cgi->param('user_id') );
 ...

Since your classes are scanned and generated, you will always take some performance hit, especially when used in non-persistant environments like a CGI application. Use "tables" liberally.

AUTHOR

Ryan Parr, <ryanparr@thejamescompany.com>

This software is based off the original work performed by Ikebe Tomohiro on the Class::DBI::Loader module.

THANKS

To Casey West for helping to hash-out what makes this module useful. To Mike Castle for submitting the first patch :)

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.