X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README;h=a827290956979dd77c5a10f0da35cefab2ffb937;hb=0101254328299030c7ab921ac546b6b91ad3ded3;hp=99ac7dd14728cec91154bae45e3bedba8083c24f;hpb=c2849787d7804fcbe541c8063e240ceff0e5ff10;p=dbsrgits%2FDBIx-Class-Schema-Loader.git diff --git a/README b/README index 99ac7dd..a827290 100644 --- a/README +++ b/README @@ -3,73 +3,69 @@ NAME DBIx::Class::Schema SYNOPSIS + ### use this module to generate a set of class files + + # in a script + use DBIx::Class::Schema::Loader qw/ make_schema_at /; + make_schema_at( + 'My::Schema', + { debug => 1, + dump_directory => './lib', + }, + [ 'dbi:Pg:dbname="foo"', 'myuser', 'mypassword' ], + ); + + # from the command line or a shell script with dbicdump (distributed + # with this module). Do `perldoc dbicdump` for usage. + dbicdump -o dump_directory=./lib \ + -o debug=1 \ + My::Schema \ + 'dbi:Pg:dbname=foo' \ + myuser \ + mypassword + + ### or generate and load classes at runtime + # note: this technique is not recommended + # for use in production code + package My::Schema; use base qw/DBIx::Class::Schema::Loader/; - __PACKAGE__->load_from_connection( - dsn => "dbi:mysql:dbname", - user => "root", - password => "", - additional_classes => [qw/DBIx::Class::Foo/], - additional_base_classes => [qw/My::Stuff/], - left_base_classes => [qw/DBIx::Class::Bar/], - components => [qw/ResultSetManager/], - resultset_components => [qw/AlwaysRS/], - constraint => '^foo.*', - relationships => 1, - options => { AutoCommit => 1 }, - inflect => { child => 'children' }, - debug => 1, + __PACKAGE__->loader_options( + constraint => '^foo.*', + # debug => 1, ); - # in seperate application code ... + #### in application code elsewhere: use My::Schema; my $schema1 = My::Schema->connect( $dsn, $user, $password, $attrs); # -or- - my $schema1 = "My::Schema"; - # ^^ defaults to dsn/user/pass from load_from_connection() - - # Get a list of the original (database) names of the tables that - # were loaded - my @tables = $schema1->loader->tables; - - # Get a hashref of table_name => 'TableName' table-to-moniker - # mappings. - my $monikers = $schema1->loader->monikers; - - # Get a hashref of table_name => 'My::Schema::TableName' - # table-to-classname mappings. - my $classes = $schema1->loader->classes; - - # Use the schema as per normal for DBIx::Class::Schema - my $rs = $schema1->resultset($monikers->{foo_table})->search(...); + my $schema1 = "My::Schema"; $schema1->connection(as above); DESCRIPTION DBIx::Class::Schema::Loader automates the definition of a - DBIx::Class::Schema by scanning table schemas and setting up columns and - primary keys. + DBIx::Class::Schema by scanning database table definitions and setting + up the columns, primary keys, and relationships. + + DBIx::Class::Schema::Loader currently supports only the DBI storage + type. It has explicit support for DBD::Pg, DBD::mysql, DBD::DB2, + DBD::SQLite, and DBD::Oracle. Other DBI drivers may function to a + greater or lesser degree with this loader, depending on how much of the + DBI spec they implement, and how standard their implementation is. - DBIx::Class::Schema::Loader supports MySQL, Postgres, SQLite and DB2. - See DBIx::Class::Schema::Loader::Generic for more, and - DBIx::Class::Schema::Loader::Writing for notes on writing your own - db-specific subclass for an unsupported db. + Patches to make other DBDs work correctly welcome. - This module requires DBIx::Class 0.05 or later, and obsoletes - DBIx::Class::Loader for DBIx::Class version 0.05 and later. + See DBIx::Class::Schema::Loader::DBI::Writing for notes on writing your + own vendor-specific subclass for an unsupported DBD driver. - While on the whole, the bare table definitions are fairly - straightforward, relationship creation is somewhat heuristic, especially - in the choosing of relationship types, join types, and relationship - names. The relationships generated by this module will probably never be - as well-defined as hand-generated ones. Because of this, over time a - complex project will probably wish to migrate off of - DBIx::Class::Schema::Loader. + This module requires DBIx::Class 0.07006 or later, and obsoletes the + older DBIx::Class::Loader. - It is designed more to get you up and running quickly against an - existing database, or to be effective for simple situations, rather than - to be what you use in the long term for a complex database/project. + This module is designed more to get you up and running quickly against + an existing database, or to be effective for simple situations, rather + than to be what you use in the long term for a complex database/project. That being said, transitioning your code from a Schema generated by this module to one that doesn't use this module should be straightforward and @@ -77,22 +73,153 @@ DESCRIPTION down the road. METHODS - load_from_connection - Example in Synopsis above demonstrates the available arguments. For - detailed information on the arguments, see the - DBIx::Class::Schema::Loader::Generic documentation. - - loader - This is an accessor in the generated Schema class for accessing the - DBIx::Class::Schema::Loader::Generic -based loader object that was used - during construction. See the DBIx::Class::Schema::Loader::Generic docs - for more information on the available loader methods there. - -KNOWN BUGS - Aside from relationship definitions being less than ideal in general, - this version is known not to handle the case of multiple relationships - between the same pair of tables. All of the relationship code will be - overhauled on the way to 0.03, at which time that bug will be addressed. + loader_class + Argument: $loader_class + + Set the loader class to be instantiated when "connection" is called. If + the classname starts with "::", "DBIx::Class::Schema::Loader" is + prepended. Defaults to "storage_type" in DBIx::Class::Schema (which must + start with "::" when using DBIx::Class::Schema::Loader). + + This is mostly useful for subclassing existing loaders or in conjunction + with "dump_to_dir". + + loader_options + Argument: \%loader_options + + Example in Synopsis above demonstrates a few common arguments. For + detailed information on all of the arguments, most of which are only + useful in fairly complex scenarios, see the + DBIx::Class::Schema::Loader::Base documentation. + + If you intend to use "loader_options", you must call "loader_options" + before any connection is made, or embed the "loader_options" in the + connection information itself as shown below. Setting "loader_options" + after the connection has already been made is useless. + + connection + Arguments: @args + Return Value: $new_schema + + See "connection" in DBIx::Class::Schema for basic usage. + + If the final argument is a hashref, and it contains the keys + "loader_options" or "loader_class", those keys will be deleted, and + their values value will be used for the loader options or class, + respectively, just as if set via the "loader_options" or "loader_class" + methods above. + + The actual auto-loading operation (the heart of this module) will be + invoked as soon as the connection information is defined. + + clone + See "clone" in DBIx::Class::Schema. + + dump_to_dir + Argument: $directory + + Calling this as a class method on either DBIx::Class::Schema::Loader or + any derived schema class will cause all schemas to dump manual versions + of themselves to the named directory when they are loaded. In order to + be effective, this must be set before defining a connection on this + schema class or any derived object (as the loading happens as soon as + both a connection and loader_options are set, and only once per class). + + See "dump_directory" in DBIx::Class::Schema::Loader::Base for more + details on the dumping mechanism. + + This can also be set at module import time via the import option + "dump_to_dir:/foo/bar" to DBIx::Class::Schema::Loader, where "/foo/bar" + is the target directory. + + Examples: + + # My::Schema isa DBIx::Class::Schema::Loader, and has connection info + # hardcoded in the class itself: + perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1 + + # Same, but no hard-coded connection, so we must provide one: + perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)' + + # Or as a class method, as long as you get it done *before* defining a + # connection on this schema class or any derived object: + use My::Schema; + My::Schema->dump_to_dir('/foo/bar'); + My::Schema->connection(........); + + # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all + # derived schemas + use My::Schema; + use My::OtherSchema; + DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar'); + My::Schema->connection(.......); + My::OtherSchema->connection(.......); + + # Another alternative to the above: + use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |; + use My::Schema; + use My::OtherSchema; + My::Schema->connection(.......); + My::OtherSchema->connection(.......); + + make_schema_at + Arguments: $schema_class_name, \%loader_options, \@connect_info + Return Value: $schema_class_name + + This function creates a DBIx::Class schema from an existing RDBMS + schema. With the "dump_directory" option, generates a set of DBIx::Class + classes from an existing database schema read from the given dsn. + Without a "dump_directory", creates schema classes in memory at runtime + without generating on-disk class files. + + For a complete list of supported loader_options, see + DBIx::Class::Schema::Loader::Base + + This function can be imported in the usual way, as illustrated in these + Examples: + + # Simple example, creates as a new class 'New::Schema::Name' in + # memory in the running perl interpreter. + use DBIx::Class::Schema::Loader qw/ make_schema_at /; + make_schema_at( + 'New::Schema::Name', + { debug => 1 }, + [ 'dbi:Pg:dbname="foo"','postgres' ], + ); + + # Inside a script, specifying a dump directory in which to write + # class files + use DBIx::Class::Schema::Loader qw/ make_schema_at /; + make_schema_at( + 'New::Schema::Name', + { debug => 1, dump_directory => './lib' }, + [ 'dbi:Pg:dbname="foo"','postgres' ], + ); + + rescan + Return Value: @new_monikers + + Re-scans the database for newly added tables since the initial load, and + adds them to the schema at runtime, including relationships, etc. Does + not process drops or changes. + + Returns a list of the new monikers added. + +KNOWN ISSUES + Multiple Database Schemas + Currently the loader is limited to working within a single schema (using + the underlying RDBMS's definition of "schema"). If you have a + multi-schema database with inter-schema relationships (which is easy to + do in PostgreSQL or DB2 for instance), you currently can only + automatically load the tables of one schema, and relationships to tables + in other schemas will be silently ignored. + + At some point in the future, an intelligent way around this might be + devised, probably by allowing the "db_schema" option to be an arrayref + of schemas to load. + + In "normal" DBIx::Class::Schema usage, manually-defined source classes + and relationships have no problems crossing vendor schemas. AUTHOR Brandon Black, "blblack@gmail.com" @@ -102,13 +229,13 @@ AUTHOR Based upon the work of IKEBE Tomohiro THANK YOU - Adam Anderson, Andy Grundman, Autrijus Tang, Dan Kubb, David Naughton, - Randal Schwartz, Simon Flack and all the others who've helped. + Matt S Trout, all of the #dbix-class folks, and everyone who's ever sent + in a bug report or suggestion. LICENSE This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO - DBIx::Class + DBIx::Class, DBIx::Class::Manual::ExampleSchema