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 Set the loader class to be instantiated when "connection" is called. If
53 the classname starts with "::", "DBIx::Class::Schema::Loader" is
54 prepended. Defaults to "storage_type" in DBIx::Class::Schema (which must
55 start with "::" when using DBIx::Class::Schema::Loader).
57 This is mostly useful for subclassing existing loaders or in conjunction
61 Example in Synopsis above demonstrates a few common arguments. For
62 detailed information on all of the arguments, most of which are only
63 useful in fairly complex scenarios, see the
64 DBIx::Class::Schema::Loader::Base documentation.
66 If you intend to use "loader_options", you must call "loader_options"
67 before any connection is made, or embed the "loader_options" in the
68 connection information itself as shown below. Setting "loader_options"
69 after the connection has already been made is useless.
72 See DBIx::Class::Schema for basic usage.
74 If the final argument is a hashref, and it contains the keys
75 "loader_options" or "loader_class", those keys will be deleted, and
76 their values value will be used for the loader options or class,
77 respectively, just as if set via the "loader_options" or "loader_class"
80 The actual auto-loading operation (the heart of this module) will be
81 invoked as soon as the connection information is defined.
84 See DBIx::Class::Schema.
87 Argument: directory name.
89 Calling this as a class method on either DBIx::Class::Schema::Loader or
90 any derived schema class will cause all affected schemas to dump manual
91 versions of themselves to the named directory when they are loaded. In
92 order to be effective, this must be set before defining a connection on
93 this schema class or any derived object (as the loading happens as soon
94 as both a connection and loader_options are set, and only once per
97 See "dump_directory" in DBIx::Class::Schema::Loader::Base for more
98 details on the dumping mechanism.
100 This can also be set at module import time via the import option
101 "dump_to_dir:/foo/bar" to DBIx::Class::Schema::Loader, where "/foo/bar"
102 is the target directory.
106 # My::Schema isa DBIx::Class::Schema::Loader, and has connection info
107 # hardcoded in the class itself:
108 perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1
110 # Same, but no hard-coded connection, so we must provide one:
111 perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)'
113 # Or as a class method, as long as you get it done *before* defining a
114 # connection on this schema class or any derived object:
116 My::Schema->dump_to_dir('/foo/bar');
117 My::Schema->connection(........);
119 # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all
123 DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar');
124 My::Schema->connection(.......);
125 My::OtherSchema->connection(.......);
127 # Another alternative to the above:
128 use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |;
131 My::Schema->connection(.......);
132 My::OtherSchema->connection(.......);
135 This simple function allows one to create a Loader-based schema
136 in-memory on the fly without any on-disk class files of any kind. When
137 used with the "dump_directory" option, you can use this to generate a
138 rough draft manual schema from a dsn without the intermediate step of
139 creating a physical Loader-based schema class.
141 The return value is the input class name.
143 This function can be exported/imported by the normal means, as
144 illustrated in these Examples:
146 # Simple example, creates as a new class 'New::Schema::Name' in
147 # memory in the running perl interpreter.
148 use DBIx::Class::Schema::Loader qw/ make_schema_at /;
152 [ 'dbi:Pg:dbname="foo"','postgres' ],
155 # Complex: dump loaded schema to disk, all from the commandline:
156 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" ])'
158 # Same, but inside a script, and using a different way to specify the
160 use DBIx::Class::Schema::Loader qw/ make_schema_at /;
163 { debug => 1, dump_directory => './lib' },
164 [ 'dbi:Pg:dbname="foo"','postgres' ],
168 Re-scans the database for newly added tables since the initial load, and
169 adds them to the schema at runtime, including relationships, etc. Does
170 not process drops or changes.
172 Returns a list of the new monikers added.
175 Using the example in DBIx::Class::Manual::ExampleSchema as a basis
176 replace the DB::Main with the following code:
180 use base qw/DBIx::Class::Schema::Loader/;
182 __PACKAGE__->loader_options(
185 __PACKAGE__->connection('dbi:SQLite:example.db');
189 and remove the Main directory tree (optional). Every thing else should
193 Multiple Database Schemas
194 Currently the loader is limited to working within a single schema (using
195 the database vendors' definition of "schema"). If you have a
196 multi-schema database with inter-schema relationships (which is easy to
197 do in PostgreSQL or DB2 for instance), you only get to automatically
198 load the tables of one schema, and any relationships to tables in other
199 schemas will be silently ignored.
201 At some point in the future, an intelligent way around this might be
202 devised, probably by allowing the "db_schema" option to be an arrayref
205 In "normal" DBIx::Class::Schema usage, manually-defined source classes
206 and relationships have no problems crossing vendor schemas.
209 Brandon Black, "blblack@gmail.com"
211 Based on DBIx::Class::Loader by Sebastian Riedel
213 Based upon the work of IKEBE Tomohiro
216 Matt S Trout, all of the #dbix-class folks, and everyone who's ever sent
217 in a bug report or suggestion.
220 This library is free software; you can redistribute it and/or modify it
221 under the same terms as Perl itself.
224 DBIx::Class, DBIx::Class::Manual::ExampleSchema