X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README;h=3829062e4d2988cbce7ae1980b86f03a9cab9e4f;hb=refs%2Ftags%2F0.04004;hp=c7c18420e0ff0aa0d0b9f5af48d759230adf0581;hpb=f654c9721271d778d0610b18004136b9c24ce699;p=dbsrgits%2FDBIx-Class-Schema-Loader.git diff --git a/README b/README index c7c1842..3829062 100644 --- a/README +++ b/README @@ -6,18 +6,9 @@ SYNOPSIS 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/], - constraint => '^foo.*', - relationships => 1, - options => { AutoCommit => 1 }, - inflect => { child => 'children' }, - debug => 1, + __PACKAGE__->loader_options( + constraint => '^foo.*', + # debug => 1, ); # in seperate application code ... @@ -26,54 +17,183 @@ SYNOPSIS my $schema1 = My::Schema->connect( $dsn, $user, $password, $attrs); # -or- - my $schema1 = "My::Schema"; - # ^^ defaults to dsn/user/pass from load_from_connection() + my $schema1 = "My::Schema"; $schema1->connection(as above); - # Get a list of the original (database) names of the tables that - # were loaded - my @tables = $schema1->loader->tables; +DESCRIPTION + DBIx::Class::Schema::Loader automates the definition of a + DBIx::Class::Schema by scanning database table definitions and setting + up the columns, primary keys, and relationships. - # Get a hashref of table_name => 'TableName' table-to-moniker - # mappings. - my $monikers = $schema1->loader->monikers; + 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. - # Get a hashref of table_name => 'My::Schema::TableName' - # table-to-classname mappings. - my $classes = $schema1->loader->classes; + Patches to make other DBDs work correctly welcome. - # Use the schema as per normal for DBIx::Class::Schema - my $rs = $schema1->resultset($monikers->{table_table})->search(...); + See DBIx::Class::Schema::Loader::DBI::Writing for notes on writing your + own vendor-specific subclass for an unsupported DBD driver. -DESCRIPTION - THIS IS A DEVELOPMENT RELEASE. This is 0.01xxx, the first public - releases. Expect things to be broken in various ways. Expect the entire - design to be fatally flawed. Expect the interfaces to change if it - becomes neccessary. It's mostly here for people to poke at it and find - the flaws in it. 0.02 will hopefully have some sanity when we get there. + This module requires DBIx::Class 0.07006 or later, and obsoletes the + older DBIx::Class::Loader. - DBIx::Class::Schema::Loader automates the definition of a - DBIx::Class::Schema by scanning table schemas and setting up columns and - primary keys. + 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. - 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. - - This module requires DBIx::Class 0.05 or later, and obsoletes - DBIx::Class::Loader for DBIx::Class version 0.05 and later. + 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 + painless, so don't shy away from it just for fears of the transition + 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_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 + See DBIx::Class::Schema for basic usage. + + If the final argument is a hashref, and it contains a key + "loader_options", that key will be deleted, and its value will be used + for the loader options, just as if set via the "loader_options" method + above. + + The actual auto-loading operation (the heart of this module) will be + invoked as soon as the connection information is defined. + + clone + See DBIx::Class::Schema. + + dump_to_dir + Argument: directory name. + + 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 + 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 + 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. - 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. + In "normal" DBIx::Class::Schema usage, manually-defined source classes + and relationships have no problems crossing vendor schemas. AUTHOR Brandon Black, "blblack@gmail.com" @@ -83,13 +203,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