1 package DBIx::Class::Schema::Loader;
5 use base qw/DBIx::Class::Schema Class::Accessor::Grouped/;
8 use Carp::Clan qw/^DBIx::Class/;
9 use Scalar::Util 'weaken';
10 use Sub::Util 'set_subname';
11 use DBIx::Class::Schema::Loader::Utils qw/array_eq sigwarn_silencer/;
16 # Always remember to do all digits for the version even if they're 0
17 # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
18 # brain damage and presumably various other packaging systems too
19 our $VERSION = '0.07048';
21 __PACKAGE__->mk_group_accessors('inherited', qw/
31 __PACKAGE__->_loader_args({});
37 DBIx::Class::Schema::Loader - Create a DBIx::Class::Schema based on a database
41 ### use this module to generate a set of class files
44 use DBIx::Class::Schema::Loader qw/ make_schema_at /;
48 dump_directory => './lib',
50 [ 'dbi:Pg:dbname="foo"', 'myuser', 'mypassword',
51 { loader_class => 'MyLoader' } # optionally
55 # from the command line or a shell script with dbicdump (distributed
56 # with this module). Do `perldoc dbicdump` for usage.
57 dbicdump -o dump_directory=./lib \
58 -o components='["InflateColumn::DateTime"]' \
65 ### or generate and load classes at runtime
66 # note: this technique is not recommended
67 # for use in production code
70 use base qw/DBIx::Class::Schema::Loader/;
72 __PACKAGE__->loader_options(
73 constraint => '^foo.*',
77 #### in application code elsewhere:
81 my $schema1 = My::Schema->connect( $dsn, $user, $password, $attrs);
83 my $schema1 = "My::Schema"; $schema1->connection(as above);
87 DBIx::Class::Schema::Loader automates the definition of a
88 L<DBIx::Class::Schema> by scanning database table definitions and setting up
89 the columns, primary keys, unique constraints and relationships.
91 See L<dbicdump> for the C<dbicdump> utility.
93 DBIx::Class::Schema::Loader currently supports only the DBI storage type. It
94 has explicit support for L<DBD::Pg>, L<DBD::mysql>, L<DBD::DB2>,
95 L<DBD::Firebird>, L<DBD::InterBase>, L<DBD::Informix>, L<DBD::SQLAnywhere>,
96 L<DBD::SQLite>, L<DBD::Sybase> (for Sybase ASE and MSSSQL), L<DBD::ODBC> (for
97 MSSQL, MSAccess, Firebird and SQL Anywhere) L<DBD::ADO> (for MSSQL and
98 MSAccess) and L<DBD::Oracle>. Other DBI drivers may function to a greater or
99 lesser degree with this loader, depending on how much of the DBI spec they
100 implement, and how standard their implementation is.
102 Patches to make other DBDs work correctly welcome.
104 See L<DBIx::Class::Schema::Loader::DBI::Writing> for notes on writing
105 your own vendor-specific subclass for an unsupported DBD driver.
107 This module requires L<DBIx::Class> 0.08127 or later, and obsoletes the older
108 L<DBIx::Class::Loader>.
110 See L<DBIx::Class::Schema::Loader::Base> for available options.
116 The loader object, as class data on your Schema. For methods available see
117 L<DBIx::Class::Schema::Loader::Base> and L<DBIx::Class::Schema::Loader::DBI>.
130 =item Argument: $loader_class
134 Set the loader class to be instantiated when L</connection> is called.
135 If the classname starts with "::", "DBIx::Class::Schema::Loader" is
136 prepended. Defaults to L<DBIx::Class::Schema/storage_type> (which must
137 start with "::" when using L<DBIx::Class::Schema::Loader>).
139 This is mostly useful for subclassing existing loaders or in conjunction
140 with L</dump_to_dir>.
142 =head2 loader_options
146 =item Argument: \%loader_options
150 Example in Synopsis above demonstrates a few common arguments. For
151 detailed information on all of the arguments, most of which are
152 only useful in fairly complex scenarios, see the
153 L<DBIx::Class::Schema::Loader::Base> documentation.
155 If you intend to use C<loader_options>, you must call
156 C<loader_options> before any connection is made, or embed the
157 C<loader_options> in the connection information itself as shown
158 below. Setting C<loader_options> after the connection has
159 already been made is useless.
166 my %args = (ref $_[0] eq 'HASH') ? %{$_[0]} : @_;
167 $self->_loader_args(\%args);
174 my $class = ref $self || $self;
176 my $args = $self->_loader_args;
178 # temporarily copy $self's storage to class
179 my $class_storage = $class->storage;
181 $class->storage($self->storage);
182 $class->storage->set_schema($class);
185 $args->{schema} = $class;
186 $args->{schema_class} = $class;
187 $args->{dump_directory} ||= $self->dump_to_dir;
188 $args->{naming} = $self->naming if $self->naming;
189 $args->{use_namespaces} = $self->use_namespaces if defined $self->use_namespaces;
191 my $loader_class = $self->loader_class;
193 $loader_class = "DBIx::Class::Schema::Loader${loader_class}" if $loader_class =~ /^::/;
194 $args->{loader_class} = $loader_class;
197 # XXX this only works for relative storage_type, like ::DBI ...
198 my $impl = $loader_class || "DBIx::Class::Schema::Loader" . $self->storage_type;
200 $self->ensure_class_loaded($impl)
203 croak qq/Could not load loader_class "$impl": "$_"/;
206 my $loader = $impl->new(%$args);
207 if (my @roles = @{$self->loader_roles || []}) {
209 Role::Tiny->apply_roles_to_object($loader, @roles);
212 $class->loader($loader);
213 $class->loader->load;
214 $class->_loader_invoked(1);
218 $self->loader($class->loader);
219 $self->_loader_invoked(1);
221 $self->_merge_state_from($class);
224 # restore $class's storage
225 $class->storage($class_storage);
230 # FIXME This needs to be moved into DBIC at some point, otherwise we are
231 # maintaining things to do with DBIC guts, which we have no business of
232 # maintaining. But at the moment it would be just dead code in DBIC, so we'll
234 sub _merge_state_from {
235 my ($self, $from) = @_;
237 my $orig_class_mappings = $self->class_mappings;
238 my $orig_source_registrations = $self->source_registrations;
240 $self->_copy_state_from($from);
242 $self->class_mappings(__merge($orig_class_mappings, $self->class_mappings))
243 if $orig_class_mappings;
245 $self->source_registrations(__merge($orig_source_registrations, $self->source_registrations))
246 if $orig_source_registrations;
252 local $SIG{__WARN__} = sigwarn_silencer(qr/Arguments for _merge_hashes must be hash references/);
256 my $m = Hash::Merge->new('LEFT_PRECEDENT');
257 $m->set_clone_behavior(0);
264 sub _copy_state_from {
268 # older DBIC's do not have this method
269 if (try { DBIx::Class->VERSION('0.08197'); 1 }) {
270 return $self->next::method(@_);
273 # this is a copy from DBIC git master pre 0.08197
274 $self->class_mappings({ %{$from->class_mappings} });
275 $self->source_registrations({ %{$from->source_registrations} });
277 foreach my $moniker ($from->sources) {
278 my $source = $from->source($moniker);
279 my $new = $source->new($source);
280 # we use extra here as we want to leave the class_mappings as they are
281 # but overwrite the source_registrations entry with the new source
282 $self->register_extra_source($moniker => $new);
285 if ($from->storage) {
286 $self->storage($from->storage);
287 $self->storage->set_schema($self);
296 =item Arguments: @args
298 =item Return Value: $new_schema
302 See L<DBIx::Class::Schema/connection> for basic usage.
304 If the final argument is a hashref, and it contains the keys C<loader_options>,
305 C<loader_class> or C<loader_roles>, those keys will be deleted, and their values
306 value will be used for the loader options or class, respectively, just as if set
307 via the L</loader_options> or L</loader_class> methods above.
309 The actual auto-loading operation (the heart of this module) will be invoked
310 as soon as the connection information is defined.
316 my $class = ref $self || $self;
318 if($_[-1] && ref $_[-1] eq 'HASH') {
319 for my $option (qw/loader_class loader_options loader_roles/) {
320 if(my $value = delete $_[-1]->{$option}) {
321 $self->$option($value);
324 pop @_ if !keys %{$_[-1]};
327 # Make sure we inherit from schema_base_class and load schema_components
329 require DBIx::Class::Schema::Loader::Base;
330 my $temp_loader = DBIx::Class::Schema::Loader::Base->new(
331 %{ $self->_loader_args },
340 if ($temp_loader->schema_base_class || $temp_loader->schema_components) {
341 @components = @{ $temp_loader->schema_components }
342 if $temp_loader->schema_components;
344 push @components, ('+'.$temp_loader->schema_base_class)
345 if $temp_loader->schema_base_class;
352 my @component_classes = map {
353 /^\+/ ? substr($_, 1, length($_) - 1) : "DBIx::Class::$_"
356 $modify_isa++ if not array_eq([ @$class_isa[0..(@components-1)] ], \@component_classes)
360 $class->load_components(@components);
362 # This hack is necessary because we changed @ISA of $self through
363 # ->load_components and we are now in a different place in the mro.
364 no warnings 'redefine';
366 local *connection = set_subname __PACKAGE__.'::connection' => sub {
368 $self->next::method(@_);
371 my @linear_isa = @{ mro::get_linear_isa($class) };
375 foreach my $i (1..$#linear_isa) {
377 $next_method = *{$linear_isa[$i].'::connection'}{CODE};
378 last if $next_method;
381 $self = $self->$next_method(@_);
384 $self = $self->next::method(@_);
387 if(!$class->_loader_invoked) {
388 $self->_invoke_loader
396 See L<DBIx::Class::Schema/clone>.
403 my $clone = $self->next::method(@_);
405 if($clone->_loader_args) {
406 $clone->_loader_args->{schema} = $clone;
407 weaken($clone->_loader_args->{schema});
417 =item Argument: $directory
421 Calling this as a class method on either L<DBIx::Class::Schema::Loader>
422 or any derived schema class will cause all schemas to dump
423 manual versions of themselves to the named directory when they are
424 loaded. In order to be effective, this must be set before defining a
425 connection on this schema class or any derived object (as the loading
426 happens as soon as both a connection and loader_options are set, and
427 only once per class).
429 See L<DBIx::Class::Schema::Loader::Base/dump_directory> for more
430 details on the dumping mechanism.
432 This can also be set at module import time via the import option
433 C<dump_to_dir:/foo/bar> to L<DBIx::Class::Schema::Loader>, where
434 C</foo/bar> is the target directory.
438 # My::Schema isa DBIx::Class::Schema::Loader, and has connection info
439 # hardcoded in the class itself:
440 perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1
442 # Same, but no hard-coded connection, so we must provide one:
443 perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)'
445 # Or as a class method, as long as you get it done *before* defining a
446 # connection on this schema class or any derived object:
448 My::Schema->dump_to_dir('/foo/bar');
449 My::Schema->connection(........);
451 # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all
455 DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar');
456 My::Schema->connection(.......);
457 My::OtherSchema->connection(.......);
459 # Another alternative to the above:
460 use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |;
463 My::Schema->connection(.......);
464 My::OtherSchema->connection(.......);
473 my $cpkg = (caller)[0];
475 foreach my $opt (@_) {
476 if($opt =~ m{^dump_to_dir:(.*)$}) {
477 $self->dump_to_dir($1)
479 elsif($opt eq 'make_schema_at') {
481 *{"${cpkg}::make_schema_at"} = \&make_schema_at;
483 elsif($opt eq 'naming') {
485 *{"${cpkg}::naming"} = $self->curry::naming;
487 elsif($opt eq 'use_namespaces') {
489 *{"${cpkg}::use_namespaces"} = $self->curry::use_namespaces,
494 =head2 make_schema_at
498 =item Arguments: $schema_class_name, \%loader_options, \@connect_info
500 =item Return Value: $schema_class_name
504 This function creates a DBIx::Class schema from an existing RDBMS
505 schema. With the C<dump_directory> option, generates a set of
506 DBIx::Class classes from an existing database schema read from the
507 given dsn. Without a C<dump_directory>, creates schema classes in
508 memory at runtime without generating on-disk class files.
510 For a complete list of supported loader_options, see
511 L<DBIx::Class::Schema::Loader::Base>
513 The last hashref in the C<\@connect_info> can specify the L</loader_class>.
515 This function can be imported in the usual way, as illustrated in
518 # Simple example, creates as a new class 'New::Schema::Name' in
519 # memory in the running perl interpreter.
520 use DBIx::Class::Schema::Loader qw/ make_schema_at /;
524 [ 'dbi:Pg:dbname="foo"','postgres','',
525 { loader_class => 'MyLoader' } # optionally
529 # Inside a script, specifying a dump directory in which to write
531 use DBIx::Class::Schema::Loader qw/ make_schema_at /;
534 { debug => 1, dump_directory => './lib' },
535 [ 'dbi:Pg:dbname="foo"','postgres','',
536 { loader_class => 'MyLoader' } # optionally
540 The last hashref in the C<\@connect_info> is checked for loader arguments such
541 as C<loader_options> and C<loader_class>, see L</connection> for more details.
546 my ($target, $opts, $connect_info) = @_;
550 @{$target . '::ISA'} = qw/DBIx::Class::Schema::Loader/;
553 $target->_loader_invoked(0);
555 $target->loader_options($opts);
557 my $temp_schema = $target->connect(@$connect_info);
559 $target->storage($temp_schema->storage);
560 $target->storage->set_schema($target);
569 =item Return Value: @new_monikers
573 Re-scans the database for newly added tables since the initial
574 load, and adds them to the schema at runtime, including relationships,
575 etc. Does not process drops or changes.
577 Returns a list of the new monikers added.
581 sub rescan { my $self = shift; $self->loader->rescan($self) }
587 =item Arguments: \%opts | $ver
591 Controls the naming options for backward compatibility, see
592 L<DBIx::Class::Schema::Loader::Base/naming> for details.
594 To upgrade a dynamic schema, use:
596 __PACKAGE__->naming('current');
598 Can be imported into your dump script and called as a function as well:
602 =head2 use_namespaces
610 Controls the use_namespaces options for backward compatibility, see
611 L<DBIx::Class::Schema::Loader::Base/use_namespaces> for details.
613 To upgrade a dynamic schema, use:
615 __PACKAGE__->use_namespaces(1);
617 Can be imported into your dump script and called as a function as well:
623 =head2 Multiple Database Schemas
625 See L<DBIx::Class::Schema::Loader::Base/db_schema>.
627 =head1 ACKNOWLEDGEMENTS
629 Matt S Trout, all of the #dbix-class folks, and everyone who's ever sent
630 in a bug report or suggestion.
632 Based on L<DBIx::Class::Loader> by Sebastian Riedel
634 Based upon the work of IKEBE Tomohiro
638 Caelum: Rafael Kitover <rkitover@cpan.org>
640 Dag-Erling Smørgrav <des@des.no>
642 Matias E. Fernandez <mfernandez@pisco.ch>
644 SineSwiper: Brendan Byrd <byrd.b@insightcom.com>
646 TSUNODA Kazuya <drk@drk7.jp>
648 acmoore: Andrew Moore <amoore@cpan.org>
650 alnewkirk: Al Newkirk <awncorp@cpan.org>
652 andrewalker: André Walker <andre@andrewalker.net>
654 angelixd: Paul C. Mantz <pcmantz@cpan.org>
656 arc: Aaron Crane <arc@cpan.org>
658 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
660 ash: Ash Berlin <ash@cpan.org>
662 blblack: Brandon Black <blblack@gmail.com>
664 bphillips: Brian Phillips <bphillips@cpan.org>
666 btilly: Ben Tilly <btilly@gmail.com>
668 domm: Thomas Klausner <domm@plix.at>
670 gugu: Andrey Kostenko <a.kostenko@rambler-co.ru>
672 hobbs: Andrew Rodland <arodland@cpan.org>
674 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
676 jhannah: Jay Hannah <jay@jays.net>
678 jnap: John Napiorkowski <jjn1056@yahoo.com>
680 kane: Jos Boumans <kane@cpan.org>
682 mattp: Matt Phillips <mattp@cpan.org>
684 mephinet: Philipp Gortan <philipp.gortan@apa.at>
686 moritz: Moritz Lenz <moritz@faui2k3.org>
688 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
690 mstratman: Mark A. Stratman <stratman@gmail.com>
692 oalders: Olaf Alders <olaf@wundersolutions.com>
694 rbo: Robert Bohne <rbo@cpan.org>
696 rbuels: Robert Buels <rbuels@gmail.com>
698 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
700 schwern: Michael G. Schwern <mschwern@cpan.org>
702 spb: Stephen Bennett <spb@exherbo.org>
704 timbunce: Tim Bunce <timb@cpan.org>
706 waawaamilk: Nigel McNie <nigel@mcnie.name>
708 ... and lots of other folks. If we forgot you, please write the current
711 =head1 COPYRIGHT & LICENSE
713 Copyright (c) 2006 - 2015 by the aforementioned
714 L<DBIx::Class::Schema::Loader/AUTHORS>.
716 This library is free software; you can redistribute it and/or modify it under
717 the same terms as Perl itself.
721 L<DBIx::Class>, L<DBIx::Class::Manual::Intro>, L<DBIx::Class::Tutorial>,
722 L<DBIx::Class::Schema::Loader::Base>
727 # vim:et sts=4 sw=4 tw=0: