/ 
Class-DBI-Schema2Code-1.01
/ Class::DBI::Schema2Code

NAME

Class::DBI::Schema2Code - Convert db schema to modules which use Class::DBI

Synopsis

Description

Class::DBI::Schema2Code is a pure Perl module.

This module allows you to convert a database schema into the corresponding set of Perl modules, all of which use Class::DBI.

One module is generated for each table in the schema.

This module uses HTML::Template, and templates compatible with that module, to generate the code.

The demonstration program examples/generator.pl skips any table called 'sessions', since CGI::Session uses a table of that name, and such a table does not use the same convention I do to name columns.

The dmeonstration program examples/reporter.pl prints out all records in a sample database.

Distributions

This module is available both as a Unix-style distro (*.tgz) and an ActiveState-style distro (*.ppd). The latter is shipped in a *.zip file.

See http://savage.net.au/Perl-modules.html for details.

See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing each type of distro.

Which Database and What Defaults?

This article:

http://www.perl.com/pub/a/2003/07/15/nocode.html

says:

Our base class inherits from Class::DBI::mysql instead of plain Class::DBI,
so we can save ourselves the trouble of directly specifying the table
columns for each of our database tables--the database-specific base
classes will auto-create a set_up_table method to handle all this for you.

I did not test this feature, and do not use it, mainly because I have to ship and support systems which run identically under MySQL and Postgres.

This latter constraint should explain the subs in parent-module.tmpl. Rather than generating code based on a DSN containing 'mysql', and also generating code based on a DSN containing 'Pg', I have included templates which have a sub get_driver() in the parent template, and which have __PACKAGE__ - sequence(...)> code in the generic template.

Simply edit the templates to suit your environment.

Constructor and initialization

new(...) returns a Class::DBI::Schema2Code object.

This is the class's contructor.

Usage: Class::DBI::Schema2Code -> new(base_name => 'Local::Project', dbh => $dbh).

new() takes at least 2 parameters.

base_name => 'Local::Project'

This is the base name of the classes which will be generated.

So, the template parent-module.tmpl will be used to generate Project.pm, and will write it into /perl/site/lib/Local/Project.pm (by default).

Also, the template generic-module.tmpl will be used to generate X.pm for each table x, and will write each such module into /perl/site/lib/Local/Project/X.pm.

See module_path, below, for how to influence the output path.

Tables with names like abc_xyz will be converted to modules with names in the studly caps format: AbcXyz.pm.

The default for this parameter is '' (the empty string).

This parameter is mandatory.

dbh => $dbh

A database handle, used to call DBI's table_info via DBIx::Admin::TableInfo.

This provides the list of table names and column names per table, which are then used to generate the code.

The default for this parameter is '' (the empty string).

This parameter is mandatory.

generic_module => 'generic-module.tmpl'

This is the name of the file containing the template for generic modules, which means those modules generated at a rate of 1 per table.

The default for this parameter is 'generic-module.tmpl'.

This parameter is optional.

mkpath => <An octal number>

This is the permissions parameter passed as the 3rd parameter to mkpath, used when creating (if necessary) the directory structure to write to.

The default for this parameter is 0777.

This parameter is optional.

module_path => '/perl/site/lib/'

This is the prefix of the path to which the generated modules will be written.

The default for this parameter is '/perl/site/lib/'.

This parameter is optional.

parent_module => 'parent-module.tmpl'

This is the name of the file containing the template for the parent module, from which all the other modules will inherit.

The default for this parameter is 'parent-module.tmpl'.

This parameter is optional.

template_path => '/apache2/htdocs/templates/schema2code'

This is the path used by HTML::Template to find the 2 templates given by the values of the parameters generic_module and parent_module.

The default for this parameter is '/apache2/htdocs/templates/schema2code'.

This parameter is optional.

Method: generate_generic_module($table_name)

Takes 1 parameter, the name of a table.

This method uses the template 'generic-module.tmpl' (by default) to generate the Perl module for the given table.

Method: generate_parent_module($username, $password)

Takes 2 parameters, a username and a password.

This method uses the template 'parent-module.tmpl' (by default) to generate the Perl module from which all the other generated modules will inherit.

The username and password are injected into the output code in order to be passed to Class::DBI::set_db() for logging on to the database.

Method: studly_caps($s)

Takes 1 parameter, a string.

Returns a StudlyCaps version of the given string.

Eg: campus_type will be turned into CampusType.

Good for converting database table names into Perl module names.

Method: tables()

Takes no parameters.

Returns an array ref containing the names of the tables.

Example code

The directory examples/ contains sample code of various types:

address.txt

Sample data read by bootstrap.pl.

campus.txt

Sample data read by bootstrap.pl.

campus_type.txt

Sample data read by bootstrap.pl.

bootstrap.pl

A program which creates a database containing 3 linked tables, and populates those tables.

Note: This program requires DBIx::Table2Hash.

generator.pl

A program which generates a set of classes for the sample database.

address-print.pl

A fragment of code for you to plug into the generated file Address.pm, to better exercise reporter.pl. It replaces sub print() in Address.pm.

campus-print.pl

A fragment of code for you to plug into the generated file Campus.pm, to better exercise reporter.pl. It replaces sub print() in Campus.pm.

reporter.pl

A program which tests some of the generated classes.

reporter.log

The output from a run of reporter.pl after those 2 sub print()s were plugged into their respective modules.

Your output should be identical, apart from OS-dependent line terminators.

Required Modules

DBI, DBIx::Admin::TableInfo, File::Path, HTML::Template;

The tests require Test::More.

The program examples/bootstrap.pl requires DBIx::Table2Hash.

Resources

This article is still excellent, despite being slightly out-of-date:

http://www.perl.com/pub/a/2003/07/15/nocode.html

See Also

Since the generated code uses Class::DBI, you really should investigate that module.

The documentation for Class::DBI has a long section called 'See Also'.

To install Class::DBI you will need to have installed, in this order:

Class::Accessor
Class::Data::Inheritable
IO::Scalar
Test::More
Class::Trigger
File::Temp
Class::WhiteHole
DBI
Ima::DBI
Scalar::List::Utils

Contains List::Util

Storable
UNIVERSAL::moniker

Because of this complexity, you should install Class::DBI via the CPAN or CPANPLUS shell, if at all possible.

Author

Class::DBI::Schema2Code was written by Ron Savage <ron@savage.net.au> in 2004.

Home page: http://savage.net.au/index.html

Copyright

Australian copyright (c) 2004, Ron Savage. All rights reserved.

All Programs of mine are 'OSI Certified Open Source Software';
you can redistribute them and/or modify them under the terms of
The Artistic License, a copy of which is available at:
http://www.opensource.org/licenses/index.html