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/;
# debug => 1,
);
- # in seperate application code ...
+ #### in application code elsewhere:
use My::Schema;
down the road.
METHODS
+ 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
after the connection has already been made is useless.
connection
- See DBIx::Class::Schema for basic usage.
+ 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 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.
+ 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 DBIx::Class::Schema.
+ See "clone" in DBIx::Class::Schema.
dump_to_dir
- Argument: directory name.
+ 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).
+ 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.
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.
+ Arguments: $schema_class_name, \%loader_options, \@connect_info
+ Return Value: $schema_class_name
- The return value is the input 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.
- This function can be exported/imported by the normal means, as
- illustrated in these Examples:
+ 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.
[ '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:
+ # 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',
);
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
+ 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 only get to automatically
- load the tables of one schema, and any relationships to tables in other
- schemas will be silently ignored.
+ 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