1NAME
2 DBIx::Class::Schema::Loader - Create a DBIx::Class::Schema based on a
3 database
4
5SYNOPSIS
6 ### use this module to generate a set of class files
7
8 # in a script
9 use DBIx::Class::Schema::Loader qw/ make_schema_at /;
10 make_schema_at(
11 'My::Schema',
12 { debug => 1,
13 dump_directory => './lib',
14 },
15 [ 'dbi:Pg:dbname="foo"', 'myuser', 'mypassword',
16 { loader_class => 'MyLoader' } # optionally
17 ],
18 );
19
20 # from the command line or a shell script with dbicdump (distributed
21 # with this module). Do `perldoc dbicdump` for usage.
22 dbicdump -o dump_directory=./lib \
23 -o components='["InflateColumn::DateTime"]' \
24 -o debug=1 \
25 My::Schema \
26 'dbi:Pg:dbname=foo' \
27 myuser \
28 mypassword
29
30 ### or generate and load classes at runtime
31 # note: this technique is not recommended
32 # for use in production code
33
34 package My::Schema;
35 use base qw/DBIx::Class::Schema::Loader/;
36
37 __PACKAGE__->loader_options(
38 constraint => '^foo.*',
39 # debug => 1,
40 );
41
42 #### in application code elsewhere:
43
44 use My::Schema;
45
46 my $schema1 = My::Schema->connect( $dsn, $user, $password, $attrs);
47 # -or-
48 my $schema1 = "My::Schema"; $schema1->connection(as above);
49
50DESCRIPTION
51 DBIx::Class::Schema::Loader automates the definition of a
52 DBIx::Class::Schema by scanning database table definitions and setting
53 up the columns, primary keys, unique constraints and relationships.
54
55 See dbicdump for the "dbicdump" utility.
56
57 DBIx::Class::Schema::Loader currently supports only the DBI storage
58 type. It has explicit support for DBD::Pg, DBD::mysql, DBD::DB2,
59 DBD::Firebird, DBD::InterBase, DBD::Informix, DBD::SQLAnywhere,
60 DBD::SQLite, DBD::Sybase (for Sybase ASE and MSSSQL), DBD::ODBC (for
61 MSSQL, MSAccess, Firebird and SQL Anywhere) DBD::ADO (for MSSQL and
62 MSAccess) and DBD::Oracle. Other DBI drivers may function to a greater
63 or lesser degree with this loader, depending on how much of the DBI spec
64 they implement, and how standard their implementation is.
65
66 Patches to make other DBDs work correctly welcome.
67
68 See DBIx::Class::Schema::Loader::DBI::Writing for notes on writing your
69 own vendor-specific subclass for an unsupported DBD driver.
70
71 This module requires DBIx::Class 0.08127 or later, and obsoletes the
72 older DBIx::Class::Loader.
73
74 See DBIx::Class::Schema::Loader::Base for available options.
75
76METHODS
77 loader
78 The loader object, as class data on your Schema. For methods available
79 see DBIx::Class::Schema::Loader::Base and
80 DBIx::Class::Schema::Loader::DBI.
81
82 loader_class
83 Argument: $loader_class
84
85 Set the loader class to be instantiated when "connection" is called. If
86 the classname starts with "::", "DBIx::Class::Schema::Loader" is
87 prepended. Defaults to "storage_type" in DBIx::Class::Schema (which must
88 start with "::" when using DBIx::Class::Schema::Loader).
89
90 This is mostly useful for subclassing existing loaders or in conjunction
91 with "dump_to_dir".
92
93 loader_options
94 Argument: \%loader_options
95
96 Example in Synopsis above demonstrates a few common arguments. For
97 detailed information on all of the arguments, most of which are only
98 useful in fairly complex scenarios, see the
99 DBIx::Class::Schema::Loader::Base documentation.
100
101 If you intend to use "loader_options", you must call "loader_options"
102 before any connection is made, or embed the "loader_options" in the
103 connection information itself as shown below. Setting "loader_options"
104 after the connection has already been made is useless.
105
106 connection
107 Arguments: @args
108 Return Value: $new_schema
109
110 See "connection" in DBIx::Class::Schema for basic usage.
111
112 If the final argument is a hashref, and it contains the keys
113 "loader_options" or "loader_class", those keys will be deleted, and
114 their values value will be used for the loader options or class,
115 respectively, just as if set via the "loader_options" or "loader_class"
116 methods above.
117
118 The actual auto-loading operation (the heart of this module) will be
119 invoked as soon as the connection information is defined.
120
121 clone
122 See "clone" in DBIx::Class::Schema.
123
124 dump_to_dir
125 Argument: $directory
126
127 Calling this as a class method on either DBIx::Class::Schema::Loader or
128 any derived schema class will cause all schemas to dump manual versions
129 of themselves to the named directory when they are loaded. In order to
130 be effective, this must be set before defining a connection on this
131 schema class or any derived object (as the loading happens as soon as
132 both a connection and loader_options are set, and only once per class).
133
134 See "dump_directory" in DBIx::Class::Schema::Loader::Base for more
135 details on the dumping mechanism.
136
137 This can also be set at module import time via the import option
138 "dump_to_dir:/foo/bar" to DBIx::Class::Schema::Loader, where "/foo/bar"
139 is the target directory.
140
141 Examples:
142
143 # My::Schema isa DBIx::Class::Schema::Loader, and has connection info
144 # hardcoded in the class itself:
145 perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1
146
147 # Same, but no hard-coded connection, so we must provide one:
148 perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)'
149
150 # Or as a class method, as long as you get it done *before* defining a
151 # connection on this schema class or any derived object:
152 use My::Schema;
153 My::Schema->dump_to_dir('/foo/bar');
154 My::Schema->connection(........);
155
156 # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all
157 # derived schemas
158 use My::Schema;
159 use My::OtherSchema;
160 DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar');
161 My::Schema->connection(.......);
162 My::OtherSchema->connection(.......);
163
164 # Another alternative to the above:
165 use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |;
166 use My::Schema;
167 use My::OtherSchema;
168 My::Schema->connection(.......);
169 My::OtherSchema->connection(.......);
170
171 make_schema_at
172 Arguments: $schema_class_name, \%loader_options, \@connect_info
173 Return Value: $schema_class_name
174
175 This function creates a DBIx::Class schema from an existing RDBMS
176 schema. With the "dump_directory" option, generates a set of DBIx::Class
177 classes from an existing database schema read from the given dsn.
178 Without a "dump_directory", creates schema classes in memory at runtime
179 without generating on-disk class files.
180
181 For a complete list of supported loader_options, see
182 DBIx::Class::Schema::Loader::Base
183
184 The last hashref in the "\@connect_info" can specify the "loader_class".
185
186 This function can be imported in the usual way, as illustrated in these
187 Examples:
188
189 # Simple example, creates as a new class 'New::Schema::Name' in
190 # memory in the running perl interpreter.
191 use DBIx::Class::Schema::Loader qw/ make_schema_at /;
192 make_schema_at(
193 'New::Schema::Name',
194 { debug => 1 },
195 [ 'dbi:Pg:dbname="foo"','postgres','',
196 { loader_class => 'MyLoader' } # optionally
197 ],
198 );
199
200 # Inside a script, specifying a dump directory in which to write
201 # class files
202 use DBIx::Class::Schema::Loader qw/ make_schema_at /;
203 make_schema_at(
204 'New::Schema::Name',
205 { debug => 1, dump_directory => './lib' },
206 [ 'dbi:Pg:dbname="foo"','postgres','',
207 { loader_class => 'MyLoader' } # optionally
208 ],
209 );
210
211 The last hashref in the "\@connect_info" is checked for loader arguments
212 such as "loader_options" and "loader_class", see "connection" for more
213 details.
214
215 rescan
216 Return Value: @new_monikers
217
218 Re-scans the database for newly added tables since the initial load, and
219 adds them to the schema at runtime, including relationships, etc. Does
220 not process drops or changes.
221
222 Returns a list of the new monikers added.
223
224 naming
225 Arguments: \%opts | $ver
226
227 Controls the naming options for backward compatibility, see "naming" in
228 DBIx::Class::Schema::Loader::Base for details.
229
230 To upgrade a dynamic schema, use:
231
232 __PACKAGE__->naming('current');
233
234 Can be imported into your dump script and called as a function as well:
235
236 naming('v4');
237
238 use_namespaces
239 Arguments: 1|0
240
241 Controls the use_namespaces options for backward compatibility, see
242 "use_namespaces" in DBIx::Class::Schema::Loader::Base for details.
243
244 To upgrade a dynamic schema, use:
245
246 __PACKAGE__->use_namespaces(1);
247
248 Can be imported into your dump script and called as a function as well:
249
250 use_namespaces(1);
251
252KNOWN ISSUES
253 Multiple Database Schemas
254 See "db_schema" in DBIx::Class::Schema::Loader::Base.
255
256ACKNOWLEDGEMENTS
257 Matt S Trout, all of the #dbix-class folks, and everyone who's ever sent
258 in a bug report or suggestion.
259
260 Based on DBIx::Class::Loader by Sebastian Riedel
261
262 Based upon the work of IKEBE Tomohiro
263
264AUTHOR
265 blblack: Brandon Black <blblack@gmail.com>
266
267CONTRIBUTORS
268 ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
269
270 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
271
272 ash: Ash Berlin <ash@cpan.org>
273
274 btilly: Ben Tilly <btilly@gmail.com>
275
276 Caelum: Rafael Kitover <rkitover@cpan.org>
277
278 TSUNODA Kazuya <drk@drk7.jp>
279
280 rbo: Robert Bohne <rbo@cpan.org>
281
282 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
283
284 gugu: Andrey Kostenko <a.kostenko@rambler-co.ru>
285
286 jhannah: Jay Hannah <jay@jays.net>
287
288 jnap: John Napiorkowski <jjn1056@yahoo.com>
289
290 rbuels: Robert Buels <rbuels@gmail.com>
291
292 timbunce: Tim Bunce <timb@cpan.org>
293
294 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
295
296 mstratman: Mark A. Stratman <stratman@gmail.com>
297
298 kane: Jos Boumans <kane@cpan.org>
299
300 waawaamilk: Nigel McNie <nigel@mcnie.name>
301
302 acmoore: Andrew Moore <amoore@cpan.org>
303
304 bphillips: Brian Phillips <bphillips@cpan.org>
305
306 schwern: Michael G. Schwern <mschwern@cpan.org>
307
308 SineSwiper: Brendan Byrd <byrd.b@insightcom.com>
309
310 hobbs: Andrew Rodland <arodland@cpan.org>
311
312 domm: Thomas Klausner <domm@plix.at>
313
314 spb: Stephen Bennett <spb@exherbo.org>
315
316 Matias E. Fernandez <mfernandez@pisco.ch>
317
318 alnewkirk: Al Newkirk <awncorp@cpan.org>
319
320 angelixd: Paul C. Mantz <pcmantz@cpan.org>
321
322 andrewalker: André Walker <andre@andrewalker.net>
323
324 ... and lots of other folks. If we forgot you, please write the current
325 maintainer or RT.
326
327COPYRIGHT & LICENSE
328 Copyright (c) 2006 - 2009 by the aforementioned "AUTHOR" in
329 DBIx::Class::Schema::Loader and "CONTRIBUTORS" in
330 DBIx::Class::Schema::Loader.
331
332 This library is free software; you can redistribute it and/or modify it
333 under the same terms as Perl itself.
334
335SEE ALSO
336 DBIx::Class, DBIx::Class::Manual::Intro, DBIx::Class::Tutorial,
337 DBIx::Class::Schema::Loader::Base
338
339