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/],
- 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;
+ my $schema1 = "My::Schema"; $schema1->connection(as above);
- # Get a hashref of table_name => 'TableName' table-to-moniker
- # mappings.
- my $monikers = $schema1->loader->monikers;
+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 => 'My::Schema::TableName'
- # table-to-classname mappings.
- my $classes = $schema1->loader->classes;
+ 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.
- # Use the schema as per normal for L<DBIx::Class::Schema>
- my $rs = $schema1->resultset($monikers->{table_table})->search(...);
+ Patches to make other DBDs work correctly welcome.
-DESCRIPTION
- THIS IS A DEVELOPMENT RELEASE. This is 0.01000, the first public
- release. 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.
+ See DBIx::Class::Schema::Loader::DBI::Writing for notes on writing your
+ own vendor-specific subclass for an unsupported DBD driver.
- 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 requires DBIx::Class 0.07006 or later, and obsoletes the
+ older DBIx::Class::Loader.
- 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 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::Loader 0.5 or later, and obsoletes
- DBIx::Class::Loader for DBIx::Class version 0.5 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_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, "bblack@gmail.com"
+ Brandon Black, "blblack@gmail.com"
Based on DBIx::Class::Loader by Sebastian Riedel
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