X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README;h=7803c50222a3ce89502f44e845c6803f4a1c965a;hb=refs%2Ftags%2F0.04999_06;hp=ef4f9a9b87c1844dddada452dbbeed059de49e25;hpb=4350370d05951cb95281948ba2d7ff0910feb364;p=dbsrgits%2FDBIx-Class-Schema-Loader.git diff --git a/README b/README index ef4f9a9..7803c50 100644 --- a/README +++ b/README @@ -6,27 +6,9 @@ SYNOPSIS package My::Schema; use base qw/DBIx::Class::Schema::Loader/; - sub _monikerize { - my $name = shift; - $name = join '', map ucfirst, split /[\W_]+/, lc $name; - $name; - } - - __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_map => { child => 'children' }, - moniker_map => \&_monikerize, - debug => 1, + __PACKAGE__->loader_options( + constraint => '^foo.*', + # debug => 1, ); # in seperate application code ... @@ -35,48 +17,30 @@ SYNOPSIS 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 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. + 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. - This module requires DBIx::Class 0.05 or later, and obsoletes - DBIx::Class::Loader for DBIx::Class version 0.05 and later. + Patches to make other DBDs work correctly welcome. - 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. + See DBIx::Class::Schema::Loader::DBI::Writing for notes on writing your + own vendor-specific subclass for an unsupported DBD driver. - 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 requires DBIx::Class 0.07006 or later, and obsoletes the + older DBIx::Class::Loader. + + 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 @@ -84,22 +48,174 @@ 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 affected 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_name, \%loader_options, \@connect_info + Return Value: $schema_name + + This simple function allows one to create a Loader-based schema + in-memory on the fly without any on-disk class files of any kind. When + used with the "dump_directory" option, you can use this to generate a + rough draft manual schema from a dsn without the intermediate step of + creating a physical Loader-based schema class. + + The return value is the input class name. + + This function can be exported/imported by the normal means, 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' ], + ); + + # Complex: dump loaded schema to disk, all from the commandline: + perl -MDBIx::Class::Schema::Loader=make_schema_at,dump_to_dir:./lib -e 'make_schema_at("New::Schema::Name", { debug => 1 }, [ "dbi:Pg:dbname=foo","postgres" ])' + + # Same, but inside a script, and using a different way to specify the + # dump directory: + 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. + +EXAMPLE + Using the example in DBIx::Class::Manual::ExampleSchema as a basis + replace the DB::Main with the following code: + + package DB::Main; + + use base qw/DBIx::Class::Schema::Loader/; + + __PACKAGE__->loader_options( + debug => 1, + ); + __PACKAGE__->connection('dbi:SQLite:example.db'); + + 1; + + and remove the Main directory tree (optional). Every thing else should + work the same + +KNOWN ISSUES + Multiple Database Schemas + Currently the loader is limited to working within a single schema (using + the database vendors' 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 only get to automatically + load the tables of one schema, and any 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" @@ -109,13 +225,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