1 package DBIx::Class::Schema::Loader;
5 use base qw/DBIx::Class::Schema Class::Accessor::Grouped/;
7 use Carp::Clan qw/^DBIx::Class/;
8 use Scalar::Util 'weaken';
11 # Always remember to do all digits for the version even if they're 0
12 # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
13 # brain damage and presumably various other packaging systems too
14 our $VERSION = '0.07010';
16 __PACKAGE__->mk_group_accessors('inherited', qw/
25 __PACKAGE__->_loader_args({});
29 DBIx::Class::Schema::Loader - Dynamic definition of a DBIx::Class::Schema
33 ### use this module to generate a set of class files
36 use DBIx::Class::Schema::Loader qw/ make_schema_at /;
40 dump_directory => './lib',
42 [ 'dbi:Pg:dbname="foo"', 'myuser', 'mypassword',
43 { loader_class => 'MyLoader' } # optionally
47 # from the command line or a shell script with dbicdump (distributed
48 # with this module). Do `perldoc dbicdump` for usage.
49 dbicdump -o dump_directory=./lib \
56 ### or generate and load classes at runtime
57 # note: this technique is not recommended
58 # for use in production code
61 use base qw/DBIx::Class::Schema::Loader/;
63 __PACKAGE__->loader_options(
64 constraint => '^foo.*',
68 #### in application code elsewhere:
72 my $schema1 = My::Schema->connect( $dsn, $user, $password, $attrs);
74 my $schema1 = "My::Schema"; $schema1->connection(as above);
78 DBIx::Class::Schema::Loader automates the definition of a
79 L<DBIx::Class::Schema> by scanning database table definitions and
80 setting up the columns, primary keys, and relationships.
82 See L<dbicdump> for the C<dbicdump> utility.
84 DBIx::Class::Schema::Loader currently supports only the DBI storage type. It
85 has explicit support for L<DBD::Pg>, L<DBD::mysql>, L<DBD::DB2>,
86 L<DBD::SQLite>, L<DBD::Sybase> (for Sybase ASE and MSSSQL), L<DBD::ODBC> (for
87 MSSQL) and L<DBD::Oracle>. Other DBI drivers may function to a greater or
88 lesser degree with this loader, depending on how much of the DBI spec they
89 implement, and how standard their implementation is.
91 Patches to make other DBDs work correctly welcome.
93 See L<DBIx::Class::Schema::Loader::DBI::Writing> for notes on writing
94 your own vendor-specific subclass for an unsupported DBD driver.
96 This module requires L<DBIx::Class> 0.07006 or later, and obsoletes
97 the older L<DBIx::Class::Loader>.
99 This module is designed more to get you up and running quickly against
100 an existing database, or to be effective for simple situations, rather
101 than to be what you use in the long term for a complex database/project.
103 That being said, transitioning your code from a Schema generated by this
104 module to one that doesn't use this module should be straightforward and
105 painless, so don't shy away from it just for fears of the transition down
112 The loader object, as class data on your Schema. For methods available see L<DBIx::Class::Schema::Loader::Base> and L<DBIx::Class::Schema::Loader::DBI>.
125 =item Argument: $loader_class
129 Set the loader class to be instantiated when L</connection> is called.
130 If the classname starts with "::", "DBIx::Class::Schema::Loader" is
131 prepended. Defaults to L<DBIx::Class::Schema/storage_type> (which must
132 start with "::" when using L<DBIx::Class::Schema::Loader>).
134 This is mostly useful for subclassing existing loaders or in conjunction
135 with L</dump_to_dir>.
137 =head2 loader_options
141 =item Argument: \%loader_options
145 Example in Synopsis above demonstrates a few common arguments. For
146 detailed information on all of the arguments, most of which are
147 only useful in fairly complex scenarios, see the
148 L<DBIx::Class::Schema::Loader::Base> documentation.
150 If you intend to use C<loader_options>, you must call
151 C<loader_options> before any connection is made, or embed the
152 C<loader_options> in the connection information itself as shown
153 below. Setting C<loader_options> after the connection has
154 already been made is useless.
161 my %args = (ref $_[0] eq 'HASH') ? %{$_[0]} : @_;
162 $self->_loader_args(\%args);
169 my $class = ref $self || $self;
171 my $args = $self->_loader_args;
173 # set up the schema/schema_class arguments
174 $args->{schema} = $self;
175 $args->{schema_class} = $class;
176 weaken($args->{schema}) if ref $self;
177 $args->{dump_directory} ||= $self->dump_to_dir;
178 $args->{naming} = $self->naming if $self->naming;
179 $args->{use_namespaces} = $self->use_namespaces if defined $self->use_namespaces;
181 # XXX this only works for relative storage_type, like ::DBI ...
182 my $loader_class = $self->loader_class;
184 $loader_class = "DBIx::Class::Schema::Loader${loader_class}" if $loader_class =~ /^::/;
185 $args->{loader_class} = $loader_class;
188 my $impl = $loader_class || "DBIx::Class::Schema::Loader" . $self->storage_type;
189 eval { $self->ensure_class_loaded($impl) };
190 croak qq/Could not load loader_class "$impl": "$@"/ if $@;
192 $self->loader($impl->new(%$args));
194 $self->_loader_invoked(1);
203 =item Arguments: @args
205 =item Return Value: $new_schema
209 See L<DBIx::Class::Schema/connection> for basic usage.
211 If the final argument is a hashref, and it contains the keys C<loader_options>
212 or C<loader_class>, those keys will be deleted, and their values value will be
213 used for the loader options or class, respectively, just as if set via the
214 L</loader_options> or L</loader_class> methods above.
216 The actual auto-loading operation (the heart of this module) will be invoked
217 as soon as the connection information is defined.
224 if($_[-1] && ref $_[-1] eq 'HASH') {
225 for my $option (qw/ loader_class loader_options result_base_class schema_base_class/) {
226 if(my $value = delete $_[-1]->{$option}) {
227 $self->$option($value);
230 pop @_ if !keys %{$_[-1]};
233 $self = $self->next::method(@_);
235 my $class = ref $self || $self;
236 if(!$class->_loader_invoked) {
237 $self->_invoke_loader
245 See L<DBIx::Class::Schema/clone>.
252 my $clone = $self->next::method(@_);
254 if($clone->_loader_args) {
255 $clone->_loader_args->{schema} = $clone;
256 weaken($clone->_loader_args->{schema});
266 =item Argument: $directory
270 Calling this as a class method on either L<DBIx::Class::Schema::Loader>
271 or any derived schema class will cause all schemas to dump
272 manual versions of themselves to the named directory when they are
273 loaded. In order to be effective, this must be set before defining a
274 connection on this schema class or any derived object (as the loading
275 happens as soon as both a connection and loader_options are set, and
276 only once per class).
278 See L<DBIx::Class::Schema::Loader::Base/dump_directory> for more
279 details on the dumping mechanism.
281 This can also be set at module import time via the import option
282 C<dump_to_dir:/foo/bar> to L<DBIx::Class::Schema::Loader>, where
283 C</foo/bar> is the target directory.
287 # My::Schema isa DBIx::Class::Schema::Loader, and has connection info
288 # hardcoded in the class itself:
289 perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1
291 # Same, but no hard-coded connection, so we must provide one:
292 perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)'
294 # Or as a class method, as long as you get it done *before* defining a
295 # connection on this schema class or any derived object:
297 My::Schema->dump_to_dir('/foo/bar');
298 My::Schema->connection(........);
300 # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all
304 DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar');
305 My::Schema->connection(.......);
306 My::OtherSchema->connection(.......);
308 # Another alternative to the above:
309 use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |;
312 My::Schema->connection(.......);
313 My::OtherSchema->connection(.......);
322 my $cpkg = (caller)[0];
324 foreach my $opt (@_) {
325 if($opt =~ m{^dump_to_dir:(.*)$}) {
326 $self->dump_to_dir($1)
328 elsif($opt eq 'make_schema_at') {
330 *{"${cpkg}::make_schema_at"} = \&make_schema_at;
332 elsif($opt eq 'naming') {
334 *{"${cpkg}::naming"} = sub { $self->naming(@_) };
336 elsif($opt eq 'use_namespaces') {
338 *{"${cpkg}::use_namespaces"} = sub { $self->use_namespaces(@_) };
343 =head2 make_schema_at
347 =item Arguments: $schema_class_name, \%loader_options, \@connect_info
349 =item Return Value: $schema_class_name
353 This function creates a DBIx::Class schema from an existing RDBMS
354 schema. With the C<dump_directory> option, generates a set of
355 DBIx::Class classes from an existing database schema read from the
356 given dsn. Without a C<dump_directory>, creates schema classes in
357 memory at runtime without generating on-disk class files.
359 For a complete list of supported loader_options, see
360 L<DBIx::Class::Schema::Loader::Base>
362 The last hashref in the C<\@connect_info> can specify the L</loader_class>.
364 This function can be imported in the usual way, as illustrated in
367 # Simple example, creates as a new class 'New::Schema::Name' in
368 # memory in the running perl interpreter.
369 use DBIx::Class::Schema::Loader qw/ make_schema_at /;
373 [ 'dbi:Pg:dbname="foo"','postgres','',
374 { loader_class => 'MyLoader' } # optionally
378 # Inside a script, specifying a dump directory in which to write
380 use DBIx::Class::Schema::Loader qw/ make_schema_at /;
383 { debug => 1, dump_directory => './lib' },
384 [ 'dbi:Pg:dbname="foo"','postgres','',
385 { loader_class => 'MyLoader' } # optionally
389 The last hashref in the C<\@connect_info> is checked for loader arguments such
390 as C<loader_options> and C<loader_class>, see L</connection> for more details.
395 my ($target, $opts, $connect_info) = @_;
399 @{$target . '::ISA'} = qw/DBIx::Class::Schema::Loader/;
402 eval { $target->_loader_invoked(0) };
404 $target->loader_options($opts);
405 $target->connection(@$connect_info);
412 =item Return Value: @new_monikers
416 Re-scans the database for newly added tables since the initial
417 load, and adds them to the schema at runtime, including relationships,
418 etc. Does not process drops or changes.
420 Returns a list of the new monikers added.
424 sub rescan { my $self = shift; $self->loader->rescan($self) }
430 =item Arguments: \%opts | $ver
434 Controls the naming options for backward compatibility, see
435 L<DBIx::Class::Schema::Loader::Base/naming> for details.
437 To upgrade a dynamic schema, use:
439 __PACKAGE__->naming('current');
441 Can be imported into your dump script and called as a function as well:
445 =head2 use_namespaces
453 Controls the use_namespaces options for backward compatibility, see
454 L<DBIx::Class::Schema::Loader::Base/use_namespaces> for details.
456 To upgrade a dynamic schema, use:
458 __PACKAGE__->use_namespaces(1);
460 Can be imported into your dump script and called as a function as well:
466 =head2 Multiple Database Schemas
468 See L<DBIx::Class::Schema::Loader::Base/db_schema>.
470 =head1 ACKNOWLEDGEMENTS
472 Matt S Trout, all of the #dbix-class folks, and everyone who's ever sent
473 in a bug report or suggestion.
475 Based on L<DBIx::Class::Loader> by Sebastian Riedel
477 Based upon the work of IKEBE Tomohiro
481 blblack: Brandon Black <blblack@gmail.com>
485 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
487 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
489 ash: Ash Berlin <ash@cpan.org>
491 btilly: Ben Tilly <btilly@gmail.com>
493 Caelum: Rafael Kitover <rkitover@cpan.org>
495 TSUNODA Kazuya <drk@drk7.jp>
497 rbo: Robert Bohne <rbo@cpan.org>
499 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
501 gugu: Andrey Kostenko <a.kostenko@rambler-co.ru>
503 jhannah: Jay Hannah <jay@jays.net>
505 rbuels: Robert Buels <rmb32@cornell.edu>
507 timbunce: Tim Bunce <timb@cpan.org>
509 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
511 mstratman: Mark A. Stratman <stratman@gmail.com>
513 kane: Jos Boumans <kane@cpan.org>
515 waawaamilk: Nigel McNie <nigel@mcnie.name>
517 acmoore: Andrew Moore <amoore@cpan.org>
519 bphillips: Brian Phillips <bphillips@cpan.org>
521 schwern: Michael G. Schwern <mschwern@cpan.org>
523 hobbs: Andrew Rodland <arodland@cpan.org>
525 domm: Thomas Klausner <domm@plix.at>
527 spb: Stephen Bennett <spb@exherbo.org>
529 Matias E. Fernandez <mfernandez@pisco.ch>
531 Al Newkirk <awncorp@cpan.org>
533 ... and lots of other folks. If we forgot you, please write the current
536 =head1 COPYRIGHT & LICENSE
538 Copyright (c) 2006 - 2009 by the aforementioned
539 L<DBIx::Class::Schema::Loader/AUTHOR> and
540 L<DBIx::Class::Schema::Loader/CONTRIBUTORS>.
542 This library is free software; you can redistribute it and/or modify it under
543 the same terms as Perl itself.
547 L<DBIx::Class>, L<DBIx::Class::Manual::ExampleSchema>
552 # vim:et sts=4 sw=4 tw=0: