DBIx::Class::Schema::Loader(3pm)

1DBIx::Class::Schema::LoUasdeerr(C3o)ntributed Perl DocumDeBnItxa:t:iColnass::Schema::Loader(3)
2
3
4

NAME

6       DBIx::Class::Schema::Loader - Dynamic definition of a
7       DBIx::Class::Schema
8

SYNOPSIS

10         ### use this module to generate a set of class files
11
12         # in a script
13         use DBIx::Class::Schema::Loader qw/ make_schema_at /;
14         make_schema_at(
15             'My::Schema',
16             { debug => 1,
17               dump_directory => './lib',
18             },
19             [ 'dbi:Pg:dbname="foo"', 'myuser', 'mypassword',
20                { loader_class => 'MyLoader' } # optionally
21             ],
22         );
23
24         # from the command line or a shell script with dbicdump (distributed
25         # with this module).  Do `perldoc dbicdump` for usage.
26         dbicdump -o dump_directory=./lib \
27                  -o debug=1 \
28                  My::Schema \
29                  'dbi:Pg:dbname=foo' \
30                  myuser \
31                  mypassword
32
33         ### or generate and load classes at runtime
34         # note: this technique is not recommended
35         # for use in production code
36
37         package My::Schema;
38         use base qw/DBIx::Class::Schema::Loader/;
39
40         __PACKAGE__->loader_options(
41             constraint              => '^foo.*',
42             # debug                 => 1,
43         );
44
45         #### in application code elsewhere:
46
47         use My::Schema;
48
49         my $schema1 = My::Schema->connect( $dsn, $user, $password, $attrs);
50         # -or-
51         my $schema1 = "My::Schema"; $schema1->connection(as above);
52

DESCRIPTION

54       DBIx::Class::Schema::Loader automates the definition of a
55       DBIx::Class::Schema by scanning database table definitions and setting
56       up the columns, primary keys, and relationships.
57
58       DBIx::Class::Schema::Loader currently supports only the DBI storage
59       type.  It has explicit support for DBD::Pg, DBD::mysql, DBD::DB2,
60       DBD::SQLite, DBD::Sybase (for Sybase ASE and MSSSQL), DBD::ODBC (for
61       MSSQL) and DBD::Oracle.  Other DBI drivers may function to a greater or
62       lesser degree with this loader, depending on how much of the DBI spec
63       they implement, and how standard their implementation is.
64
65       Patches to make other DBDs work correctly welcome.
66
67       See DBIx::Class::Schema::Loader::DBI::Writing for notes on writing your
68       own vendor-specific subclass for an unsupported DBD driver.
69
70       This module requires DBIx::Class 0.07006 or later, and obsoletes the
71       older DBIx::Class::Loader.
72
73       This module is designed more to get you up and running quickly against
74       an existing database, or to be effective for simple situations, rather
75       than to be what you use in the long term for a complex
76       database/project.
77
78       That being said, transitioning your code from a Schema generated by
79       this module to one that doesn't use this module should be
80       straightforward and painless, so don't shy away from it just for fears
81       of the transition down the road.
82

METHODS

84   loader_class
85       Argument: $loader_class
86
87       Set the loader class to be instantiated when "connection" is called.
88       If the classname starts with "::", "DBIx::Class::Schema::Loader" is
89       prepended. Defaults to "storage_type" in DBIx::Class::Schema (which
90       must start with "::" when using DBIx::Class::Schema::Loader).
91
92       This is mostly useful for subclassing existing loaders or in
93       conjunction with "dump_to_dir".
94
95   loader_options
96       Argument: \%loader_options
97
98       Example in Synopsis above demonstrates a few common arguments.  For
99       detailed information on all of the arguments, most of which are only
100       useful in fairly complex scenarios, see the
101       DBIx::Class::Schema::Loader::Base documentation.
102
103       If you intend to use "loader_options", you must call "loader_options"
104       before any connection is made, or embed the "loader_options" in the
105       connection information itself as shown below.  Setting "loader_options"
106       after the connection has already been made is useless.
107
108   connection
109       Arguments: @args
110       Return Value: $new_schema
111
112       See "connection" in DBIx::Class::Schema for basic usage.
113
114       If the final argument is a hashref, and it contains the keys
115       "loader_options" or "loader_class", those keys will be deleted, and
116       their values value will be used for the loader options or class,
117       respectively, just as if set via the "loader_options" or "loader_class"
118       methods above.
119
120       The actual auto-loading operation (the heart of this module) will be
121       invoked as soon as the connection information is defined.
122
123   clone
124       See "clone" in DBIx::Class::Schema.
125
126   dump_to_dir
127       Argument: $directory
128
129       Calling this as a class method on either DBIx::Class::Schema::Loader or
130       any derived schema class will cause all schemas to dump manual versions
131       of themselves to the named directory when they are loaded.  In order to
132       be effective, this must be set before defining a connection on this
133       schema class or any derived object (as the loading happens as soon as
134       both a connection and loader_options are set, and only once per class).
135
136       See "dump_directory" in DBIx::Class::Schema::Loader::Base for more
137       details on the dumping mechanism.
138
139       This can also be set at module import time via the import option
140       "dump_to_dir:/foo/bar" to DBIx::Class::Schema::Loader, where "/foo/bar"
141       is the target directory.
142
143       Examples:
144
145           # My::Schema isa DBIx::Class::Schema::Loader, and has connection info
146           #   hardcoded in the class itself:
147           perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1
148
149           # Same, but no hard-coded connection, so we must provide one:
150           perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)'
151
152           # Or as a class method, as long as you get it done *before* defining a
153           #  connection on this schema class or any derived object:
154           use My::Schema;
155           My::Schema->dump_to_dir('/foo/bar');
156           My::Schema->connection(........);
157
158           # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all
159           #   derived schemas
160           use My::Schema;
161           use My::OtherSchema;
162           DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar');
163           My::Schema->connection(.......);
164           My::OtherSchema->connection(.......);
165
166           # Another alternative to the above:
167           use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |;
168           use My::Schema;
169           use My::OtherSchema;
170           My::Schema->connection(.......);
171           My::OtherSchema->connection(.......);
172
173   make_schema_at
174       Arguments: $schema_class_name, \%loader_options, \@connect_info
175       Return Value: $schema_class_name
176
177       This function creates a DBIx::Class schema from an existing RDBMS
178       schema.  With the "dump_directory" option, generates a set of
179       DBIx::Class classes from an existing database schema read from the
180       given dsn.  Without a "dump_directory", creates schema classes in
181       memory at runtime without generating on-disk class files.
182
183       For a complete list of supported loader_options, see
184       DBIx::Class::Schema::Loader::Base
185
186       The last hashref in the "\@connect_info" can specify the
187       "loader_class".
188
189       This function can be imported in the usual way, as illustrated in these
190       Examples:
191
192           # Simple example, creates as a new class 'New::Schema::Name' in
193           #  memory in the running perl interpreter.
194           use DBIx::Class::Schema::Loader qw/ make_schema_at /;
195           make_schema_at(
196               'New::Schema::Name',
197               { debug => 1 },
198               [ 'dbi:Pg:dbname="foo"','postgres','',
199                 { loader_class => 'MyLoader' } # optionally
200               ],
201           );
202
203           # Inside a script, specifying a dump directory in which to write
204           # class files
205           use DBIx::Class::Schema::Loader qw/ make_schema_at /;
206           make_schema_at(
207               'New::Schema::Name',
208               { debug => 1, dump_directory => './lib' },
209               [ 'dbi:Pg:dbname="foo"','postgres','',
210                 { loader_class => 'MyLoader' } # optionally
211               ],
212           );
213
214       The last hashref in the "\@connect_info" is checked for loader
215       arguments such as "loader_options" and "loader_class", see "connection"
216       for more details.
217
218   rescan
219       Return Value: @new_monikers
220
221       Re-scans the database for newly added tables since the initial load,
222       and adds them to the schema at runtime, including relationships, etc.
223       Does not process drops or changes.
224
225       Returns a list of the new monikers added.
226
227   naming
228       Arguments: \%opts | $ver
229
230       Controls the naming options for backward compatibility, see "naming" in
231       DBIx::Class::Schema::Loader::Base for details.
232
233       To upgrade a dynamic schema, use:
234
235           __PACKAGE__->naming('current');
236
237       Can be imported into your dump script and called as a function as well:
238
239           naming('v4');
240
241   use_namespaces
242       Arguments: 1|0
243
244       Controls the use_namespaces options for backward compatibility, see
245       "use_namespaces" in DBIx::Class::Schema::Loader::Base for details.
246
247       To upgrade a dynamic schema, use:
248
249           __PACKAGE__->use_namespaces(1);
250
251       Can be imported into your dump script and called as a function as well:
252
253           use_namespaces(1);
254

KNOWN ISSUES

256   Multiple Database Schemas
257       Currently the loader is limited to working within a single schema
258       (using the underlying RDBMS's definition of "schema").  If you have a
259       multi-schema database with inter-schema relationships (which is easy to
260       do in PostgreSQL or DB2 for instance), you currently can only
261       automatically load the tables of one schema, and relationships to
262       tables in other schemas will be silently ignored.
263
264       At some point in the future, an intelligent way around this might be
265       devised, probably by allowing the "db_schema" option to be an arrayref
266       of schemas to load.
267
268       In "normal" DBIx::Class::Schema usage, manually-defined source classes
269       and relationships have no problems crossing vendor schemas.
270

ACKNOWLEDGEMENTS

272       Matt S Trout, all of the #dbix-class folks, and everyone who's ever
273       sent in a bug report or suggestion.
274
275       Based on DBIx::Class::Loader by Sebastian Riedel
276
277       Based upon the work of IKEBE Tomohiro
278

AUTHOR

280       blblack: Brandon Black <blblack@gmail.com>
281

CONTRIBUTORS

283       ilmari: Dagfinn Ilmari Mannsaaker <ilmari@ilmari.org>
284
285       arcanez: Justin Hunter <justin.d.hunter@gmail.com>
286
287       ash: Ash Berlin <ash@cpan.org>
288
289       Caelum: Rafael Kitover <rkitover@cpan.org>
290
291       TSUNODA Kazuya <drk@drk7.jp>
292
293       rbo: Robert Bohne <rbo@cpan.org>
294
295       ribasushi: Peter Rabbitson <ribasushi@cpan.org>
296
297       gugu: Andrey Kostenko <a.kostenko@rambler-co.ru>
298
299       jhannah: Jay Hannah <jay@jays.net>
300
301       rbuels: Robert Buels <rmb32@cornell.edu>
302
303       timbunce: Tim Bunce <timb@cpan.org>
304
305       mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
306
307       kane: Jos Boumans <kane@cpan.org>
308
309       waawaamilk: Nigel McNie <nigel@mcnie.name>
310
311       acmoore: Andrew Moore <amoore@cpan.org>
312
313       bphillips: Brian Phillips <bphillips@cpan.org>
314
315       schwern: Michael G. Schwern <mschwern@cpan.org>
316
317       hobbs: Andrew Rodland <arodland@cpan.org>
318
319       domm: Thomas Klausner <domm@plix.at>
320
321       ... and lots of other folks. If we forgot you, please write the current
322       maintainer or RT.
323

COPYRIGHT & LICENSE

325       Copyright (c) 2006 - 2009 by the aforementioned "AUTHOR" in
326       DBIx::Class::Schema::Loader and "CONTRIBUTORS" in
327       DBIx::Class::Schema::Loader.
328
329       This library is free software; you can redistribute it and/or modify it
330       under the same terms as Perl itself.
331