2 DBIx::Class::Schema::Loader - Dynamic definition of a
7 use base qw/DBIx::Class::Schema::Loader/;
9 __PACKAGE__->loader_options(
10 constraint => '^foo.*',
14 # in seperate application code ...
18 my $schema1 = My::Schema->connect( $dsn, $user, $password, $attrs);
20 my $schema1 = "My::Schema"; $schema1->connection(as above);
23 DBIx::Class::Schema::Loader automates the definition of a
24 DBIx::Class::Schema by scanning database table definitions and setting
25 up the columns, primary keys, and relationships.
27 DBIx::Class::Schema::Loader currently supports only the DBI storage
28 type. It has explicit support for DBD::Pg, DBD::mysql, DBD::DB2,
29 DBD::SQLite, and DBD::Oracle. Other DBI drivers may function to a
30 greater or lesser degree with this loader, depending on how much of the
31 DBI spec they implement, and how standard their implementation is.
33 Patches to make other DBDs work correctly welcome.
35 See DBIx::Class::Schema::Loader::DBI::Writing for notes on writing your
36 own vendor-specific subclass for an unsupported DBD driver.
38 This module requires DBIx::Class 0.07006 or later, and obsoletes the
39 older DBIx::Class::Loader.
41 This module is designed more to get you up and running quickly against
42 an existing database, or to be effective for simple situations, rather
43 than to be what you use in the long term for a complex database/project.
45 That being said, transitioning your code from a Schema generated by this
46 module to one that doesn't use this module should be straightforward and
47 painless, so don't shy away from it just for fears of the transition
52 Argument: $loader_class
54 Set the loader class to be instantiated when "connection" is called. If
55 the classname starts with "::", "DBIx::Class::Schema::Loader" is
56 prepended. Defaults to "storage_type" in DBIx::Class::Schema (which must
57 start with "::" when using DBIx::Class::Schema::Loader).
59 This is mostly useful for subclassing existing loaders or in conjunction
63 Argument: \%loader_options
65 Example in Synopsis above demonstrates a few common arguments. For
66 detailed information on all of the arguments, most of which are only
67 useful in fairly complex scenarios, see the
68 DBIx::Class::Schema::Loader::Base documentation.
70 If you intend to use "loader_options", you must call "loader_options"
71 before any connection is made, or embed the "loader_options" in the
72 connection information itself as shown below. Setting "loader_options"
73 after the connection has already been made is useless.
77 Return Value: $new_schema
79 See "connection" in DBIx::Class::Schema for basic usage.
81 If the final argument is a hashref, and it contains the keys
82 "loader_options" or "loader_class", those keys will be deleted, and
83 their values value will be used for the loader options or class,
84 respectively, just as if set via the "loader_options" or "loader_class"
87 The actual auto-loading operation (the heart of this module) will be
88 invoked as soon as the connection information is defined.
91 See "clone" in DBIx::Class::Schema.
96 Calling this as a class method on either DBIx::Class::Schema::Loader or
97 any derived schema class will cause all affected schemas to dump manual
98 versions of themselves to the named directory when they are loaded. In
99 order to be effective, this must be set before defining a connection on
100 this schema class or any derived object (as the loading happens as soon
101 as both a connection and loader_options are set, and only once per
104 See "dump_directory" in DBIx::Class::Schema::Loader::Base for more
105 details on the dumping mechanism.
107 This can also be set at module import time via the import option
108 "dump_to_dir:/foo/bar" to DBIx::Class::Schema::Loader, where "/foo/bar"
109 is the target directory.
113 # My::Schema isa DBIx::Class::Schema::Loader, and has connection info
114 # hardcoded in the class itself:
115 perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1
117 # Same, but no hard-coded connection, so we must provide one:
118 perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)'
120 # Or as a class method, as long as you get it done *before* defining a
121 # connection on this schema class or any derived object:
123 My::Schema->dump_to_dir('/foo/bar');
124 My::Schema->connection(........);
126 # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all
130 DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar');
131 My::Schema->connection(.......);
132 My::OtherSchema->connection(.......);
134 # Another alternative to the above:
135 use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |;
138 My::Schema->connection(.......);
139 My::OtherSchema->connection(.......);
142 Arguments: $schema_name, \%loader_options, \@connect_info
143 Return Value: $schema_name
145 This simple function allows one to create a Loader-based schema
146 in-memory on the fly without any on-disk class files of any kind. When
147 used with the "dump_directory" option, you can use this to generate a
148 rough draft manual schema from a dsn without the intermediate step of
149 creating a physical Loader-based schema class.
151 The return value is the input class name.
153 This function can be exported/imported by the normal means, as
154 illustrated in these Examples:
156 # Simple example, creates as a new class 'New::Schema::Name' in
157 # memory in the running perl interpreter.
158 use DBIx::Class::Schema::Loader qw/ make_schema_at /;
162 [ 'dbi:Pg:dbname="foo"','postgres' ],
165 # Complex: dump loaded schema to disk, all from the commandline:
166 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" ])'
168 # Same, but inside a script, and using a different way to specify the
170 use DBIx::Class::Schema::Loader qw/ make_schema_at /;
173 { debug => 1, dump_directory => './lib' },
174 [ 'dbi:Pg:dbname="foo"','postgres' ],
178 Return Value: @new_monikers
180 Re-scans the database for newly added tables since the initial load, and
181 adds them to the schema at runtime, including relationships, etc. Does
182 not process drops or changes.
184 Returns a list of the new monikers added.
187 Using the example in DBIx::Class::Manual::ExampleSchema as a basis
188 replace the DB::Main with the following code:
192 use base qw/DBIx::Class::Schema::Loader/;
194 __PACKAGE__->loader_options(
197 __PACKAGE__->connection('dbi:SQLite:example.db');
201 and remove the Main directory tree (optional). Every thing else should
205 Multiple Database Schemas
206 Currently the loader is limited to working within a single schema (using
207 the database vendors' definition of "schema"). If you have a
208 multi-schema database with inter-schema relationships (which is easy to
209 do in PostgreSQL or DB2 for instance), you only get to automatically
210 load the tables of one schema, and any relationships to tables in other
211 schemas will be silently ignored.
213 At some point in the future, an intelligent way around this might be
214 devised, probably by allowing the "db_schema" option to be an arrayref
217 In "normal" DBIx::Class::Schema usage, manually-defined source classes
218 and relationships have no problems crossing vendor schemas.
221 Brandon Black, "blblack@gmail.com"
223 Based on DBIx::Class::Loader by Sebastian Riedel
225 Based upon the work of IKEBE Tomohiro
228 Matt S Trout, all of the #dbix-class folks, and everyone who's ever sent
229 in a bug report or suggestion.
232 This library is free software; you can redistribute it and/or modify it
233 under the same terms as Perl itself.
236 DBIx::Class, DBIx::Class::Manual::ExampleSchema