lib/DBIx/Class/Schema/Loader.pm

   1 package DBIx::Class::Schema::Loader;
   2
   3 use strict;
   4 use warnings;
   5 use base qw/DBIx::Class::Schema Class::Accessor::Grouped/;
   6 use MRO::Compat;
   7 use mro 'c3';
   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 'array_eq';
  12 use Try::Tiny;
  13 use Hash::Merge 'merge';
  14 use curry;
  15 use namespace::clean;
  16
  17 # Always remember to do all digits for the version even if they're 0
  18 # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
  19 # brain damage and presumably various other packaging systems too
  20 our $VERSION = '0.07047';
  21
  22 __PACKAGE__->mk_group_accessors('inherited', qw/
  23                                 _loader_args
  24                                 dump_to_dir
  25                                 _loader_invoked
  26                                 _loader
  27                                 loader_class
  28                                 naming
  29                                 use_namespaces
  30 /);
  31 __PACKAGE__->_loader_args({});
  32
  33 =encoding UTF-8
  34
  35 =head1 NAME
  36
  37 DBIx::Class::Schema::Loader - Create a DBIx::Class::Schema based on a database
  38
  39 =head1 SYNOPSIS
  40
  41     ### use this module to generate a set of class files
  42
  43     # in a script
  44     use DBIx::Class::Schema::Loader qw/ make_schema_at /;
  45     make_schema_at(
  46         'My::Schema',
  47         { debug => 1,
  48           dump_directory => './lib',
  49         },
  50         [ 'dbi:Pg:dbname="foo"', 'myuser', 'mypassword',
  51            { loader_class => 'MyLoader' } # optionally
  52         ],
  53     );
  54
  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"]' \
  59              -o debug=1 \
  60              My::Schema \
  61              'dbi:Pg:dbname=foo' \
  62              myuser \
  63              mypassword
  64
  65     ### or generate and load classes at runtime
  66     # note: this technique is not recommended
  67     # for use in production code
  68
  69     package My::Schema;
  70     use base qw/DBIx::Class::Schema::Loader/;
  71
  72     __PACKAGE__->loader_options(
  73         constraint              => '^foo.*',
  74         # debug                 => 1,
  75     );
  76
  77     #### in application code elsewhere:
  78
  79     use My::Schema;
  80
  81     my $schema1 = My::Schema->connect( $dsn, $user, $password, $attrs);
  82     # -or-
  83     my $schema1 = "My::Schema"; $schema1->connection(as above);
  84
  85 =head1 DESCRIPTION
  86
  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.
  90
  91 See L<dbicdump> for the C<dbicdump> utility.
  92
  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.
 101
 102 Patches to make other DBDs work correctly welcome.
 103
 104 See L<DBIx::Class::Schema::Loader::DBI::Writing> for notes on writing
 105 your own vendor-specific subclass for an unsupported DBD driver.
 106
 107 This module requires L<DBIx::Class> 0.08127 or later, and obsoletes the older
 108 L<DBIx::Class::Loader>.
 109
 110 See L<DBIx::Class::Schema::Loader::Base> for available options.
 111
 112 =head1 METHODS
 113
 114 =head2 loader
 115
 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>.
 118
 119 =cut
 120
 121 sub loader {
 122     my $self = shift;
 123     $self->_loader(@_);
 124 }
 125
 126 =head2 loader_class
 127
 128 =over 4
 129
 130 =item Argument: $loader_class
 131
 132 =back
 133
 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>).
 138
 139 This is mostly useful for subclassing existing loaders or in conjunction
 140 with L</dump_to_dir>.
 141
 142 =head2 loader_options
 143
 144 =over 4
 145
 146 =item Argument: \%loader_options
 147
 148 =back
 149
 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.
 154
 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.
 160
 161 =cut
 162
 163 sub loader_options {
 164     my $self = shift;
 165
 166     my %args = (ref $_[0] eq 'HASH') ? %{$_[0]} : @_;
 167     $self->_loader_args(\%args);
 168
 169     $self;
 170 }
 171
 172 sub _invoke_loader {
 173     my $self = shift;
 174     my $class = ref $self || $self;
 175
 176     my $args = $self->_loader_args;
 177
 178     # temporarily copy $self's storage to class
 179     my $class_storage = $class->storage;
 180     if (ref $self) {
 181         $class->storage($self->storage);
 182         $class->storage->set_schema($class);
 183     }
 184
 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;
 190
 191     # XXX this only works for relative storage_type, like ::DBI ...
 192     my $loader_class = $self->loader_class;
 193     if ($loader_class) {
 194         $loader_class = "DBIx::Class::Schema::Loader${loader_class}" if $loader_class =~ /^::/;
 195         $args->{loader_class} = $loader_class;
 196     };
 197
 198     my $impl = $loader_class || "DBIx::Class::Schema::Loader" . $self->storage_type;
 199     try {
 200         $self->ensure_class_loaded($impl)
 201     }
 202     catch {
 203         croak qq/Could not load loader_class "$impl": "$_"/;
 204     };
 205
 206     $class->loader($impl->new(%$args));
 207     $class->loader->load;
 208     $class->_loader_invoked(1);
 209
 210     # copy to $self
 211     if (ref $self) {
 212         $self->loader($class->loader);
 213         $self->_loader_invoked(1);
 214
 215         $self->_merge_state_from($class);
 216     }
 217
 218     # restore $class's storage
 219     $class->storage($class_storage);
 220
 221     return $self;
 222 }
 223
 224 # FIXME This needs to be moved into DBIC at some point, otherwise we are
 225 # maintaining things to do with DBIC guts, which we have no business of
 226 # maintaining. But at the moment it would be just dead code in DBIC, so we'll
 227 # maintain it here.
 228 sub _merge_state_from {
 229     my ($self, $from) = @_;
 230
 231     my $orig_class_mappings       = $self->class_mappings;
 232     my $orig_source_registrations = $self->source_registrations;
 233
 234     $self->_copy_state_from($from);
 235
 236     $self->class_mappings(merge($orig_class_mappings, $self->class_mappings))
 237         if $orig_class_mappings;
 238
 239     $self->source_registrations(merge($orig_source_registrations, $self->source_registrations))
 240         if $orig_source_registrations;
 241 }
 242
 243 sub _copy_state_from {
 244     my $self = shift;
 245     my ($from) = @_;
 246
 247     # older DBIC's do not have this method
 248     if (try { DBIx::Class->VERSION('0.08197'); 1 }) {
 249         return $self->next::method(@_);
 250     }
 251     else {
 252         # this is a copy from DBIC git master pre 0.08197
 253         $self->class_mappings({ %{$from->class_mappings} });
 254         $self->source_registrations({ %{$from->source_registrations} });
 255
 256         foreach my $moniker ($from->sources) {
 257             my $source = $from->source($moniker);
 258             my $new = $source->new($source);
 259             # we use extra here as we want to leave the class_mappings as they are
 260             # but overwrite the source_registrations entry with the new source
 261             $self->register_extra_source($moniker => $new);
 262         }
 263
 264         if ($from->storage) {
 265             $self->storage($from->storage);
 266             $self->storage->set_schema($self);
 267         }
 268     }
 269 }
 270
 271 =head2 connection
 272
 273 =over 4
 274
 275 =item Arguments: @args
 276
 277 =item Return Value: $new_schema
 278
 279 =back
 280
 281 See L<DBIx::Class::Schema/connection> for basic usage.
 282
 283 If the final argument is a hashref, and it contains the keys C<loader_options>
 284 or C<loader_class>, those keys will be deleted, and their values value will be
 285 used for the loader options or class, respectively, just as if set via the
 286 L</loader_options> or L</loader_class> methods above.
 287
 288 The actual auto-loading operation (the heart of this module) will be invoked
 289 as soon as the connection information is defined.
 290
 291 =cut
 292
 293 sub connection {
 294     my $self  = shift;
 295     my $class = ref $self || $self;
 296
 297     if($_[-1] && ref $_[-1] eq 'HASH') {
 298         for my $option (qw/loader_class loader_options/) {
 299             if(my $value = delete $_[-1]->{$option}) {
 300                 $self->$option($value);
 301             }
 302         }
 303         pop @_ if !keys %{$_[-1]};
 304     }
 305
 306     # Make sure we inherit from schema_base_class and load schema_components
 307     # before connecting.
 308     require DBIx::Class::Schema::Loader::Base;
 309     my $temp_loader = DBIx::Class::Schema::Loader::Base->new(
 310         %{ $self->_loader_args },
 311         schema => $self,
 312         naming => 'current',
 313         use_namespaces => 1,
 314     );
 315
 316     my $modify_isa = 0;
 317     my @components;
 318
 319     if ($temp_loader->schema_base_class || $temp_loader->schema_components) {
 320         @components = @{ $temp_loader->schema_components }
 321             if $temp_loader->schema_components;
 322
 323         push @components, ('+'.$temp_loader->schema_base_class)
 324             if $temp_loader->schema_base_class;
 325
 326         my $class_isa = do {
 327             no strict 'refs';
 328             \@{"${class}::ISA"};
 329         };
 330
 331         my @component_classes = map {
 332             /^\+/ ? substr($_, 1, length($_) - 1) : "DBIx::Class::$_"
 333         } @components;
 334
 335         $modify_isa++ if not array_eq([ @$class_isa[0..(@components-1)] ], \@component_classes)
 336     }
 337
 338     if ($modify_isa) {
 339         $class->load_components(@components);
 340
 341         # This hack is necessary because we changed @ISA of $self through
 342         # ->load_components and we are now in a different place in the mro.
 343         no warnings 'redefine';
 344
 345         local *connection = set_subname __PACKAGE__.'::connection' => sub {
 346             my $self = shift;
 347             $self->next::method(@_);
 348         };
 349
 350         my @linear_isa = @{ mro::get_linear_isa($class) };
 351
 352         my $next_method;
 353
 354         foreach my $i (1..$#linear_isa) {
 355             no strict 'refs';
 356             $next_method = *{$linear_isa[$i].'::connection'}{CODE};
 357             last if $next_method;
 358         }
 359
 360         $self = $self->$next_method(@_);
 361     }
 362     else {
 363         $self = $self->next::method(@_);
 364     }
 365
 366     if(!$class->_loader_invoked) {
 367         $self->_invoke_loader
 368     }
 369
 370     return $self;
 371 }
 372
 373 =head2 clone
 374
 375 See L<DBIx::Class::Schema/clone>.
 376
 377 =cut
 378
 379 sub clone {
 380     my $self = shift;
 381
 382     my $clone = $self->next::method(@_);
 383
 384     if($clone->_loader_args) {
 385         $clone->_loader_args->{schema} = $clone;
 386         weaken($clone->_loader_args->{schema});
 387     }
 388
 389     $clone;
 390 }
 391
 392 =head2 dump_to_dir
 393
 394 =over 4
 395
 396 =item Argument: $directory
 397
 398 =back
 399
 400 Calling this as a class method on either L<DBIx::Class::Schema::Loader>
 401 or any derived schema class will cause all schemas to dump
 402 manual versions of themselves to the named directory when they are
 403 loaded.  In order to be effective, this must be set before defining a
 404 connection on this schema class or any derived object (as the loading
 405 happens as soon as both a connection and loader_options are set, and
 406 only once per class).
 407
 408 See L<DBIx::Class::Schema::Loader::Base/dump_directory> for more
 409 details on the dumping mechanism.
 410
 411 This can also be set at module import time via the import option
 412 C<dump_to_dir:/foo/bar> to L<DBIx::Class::Schema::Loader>, where
 413 C</foo/bar> is the target directory.
 414
 415 Examples:
 416
 417     # My::Schema isa DBIx::Class::Schema::Loader, and has connection info
 418     #   hardcoded in the class itself:
 419     perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1
 420
 421     # Same, but no hard-coded connection, so we must provide one:
 422     perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)'
 423
 424     # Or as a class method, as long as you get it done *before* defining a
 425     #  connection on this schema class or any derived object:
 426     use My::Schema;
 427     My::Schema->dump_to_dir('/foo/bar');
 428     My::Schema->connection(........);
 429
 430     # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all
 431     #   derived schemas
 432     use My::Schema;
 433     use My::OtherSchema;
 434     DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar');
 435     My::Schema->connection(.......);
 436     My::OtherSchema->connection(.......);
 437
 438     # Another alternative to the above:
 439     use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |;
 440     use My::Schema;
 441     use My::OtherSchema;
 442     My::Schema->connection(.......);
 443     My::OtherSchema->connection(.......);
 444
 445 =cut
 446
 447 sub import {
 448     my $self = shift;
 449
 450     return if !@_;
 451
 452     my $cpkg = (caller)[0];
 453
 454     foreach my $opt (@_) {
 455         if($opt =~ m{^dump_to_dir:(.*)$}) {
 456             $self->dump_to_dir($1)
 457         }
 458         elsif($opt eq 'make_schema_at') {
 459             no strict 'refs';
 460             *{"${cpkg}::make_schema_at"} = \&make_schema_at;
 461         }
 462         elsif($opt eq 'naming') {
 463             no strict 'refs';
 464             *{"${cpkg}::naming"} = $self->curry::naming;
 465         }
 466         elsif($opt eq 'use_namespaces') {
 467             no strict 'refs';
 468             *{"${cpkg}::use_namespaces"} = $self->curry::use_namespaces,
 469         }
 470     }
 471 }
 472
 473 =head2 make_schema_at
 474
 475 =over 4
 476
 477 =item Arguments: $schema_class_name, \%loader_options, \@connect_info
 478
 479 =item Return Value: $schema_class_name
 480
 481 =back
 482
 483 This function creates a DBIx::Class schema from an existing RDBMS
 484 schema.  With the C<dump_directory> option, generates a set of
 485 DBIx::Class classes from an existing database schema read from the
 486 given dsn.  Without a C<dump_directory>, creates schema classes in
 487 memory at runtime without generating on-disk class files.
 488
 489 For a complete list of supported loader_options, see
 490 L<DBIx::Class::Schema::Loader::Base>
 491
 492 The last hashref in the C<\@connect_info> can specify the L</loader_class>.
 493
 494 This function can be imported in the usual way, as illustrated in
 495 these Examples:
 496
 497     # Simple example, creates as a new class 'New::Schema::Name' in
 498     #  memory in the running perl interpreter.
 499     use DBIx::Class::Schema::Loader qw/ make_schema_at /;
 500     make_schema_at(
 501         'New::Schema::Name',
 502         { debug => 1 },
 503         [ 'dbi:Pg:dbname="foo"','postgres','',
 504           { loader_class => 'MyLoader' } # optionally
 505         ],
 506     );
 507
 508     # Inside a script, specifying a dump directory in which to write
 509     # class files
 510     use DBIx::Class::Schema::Loader qw/ make_schema_at /;
 511     make_schema_at(
 512         'New::Schema::Name',
 513         { debug => 1, dump_directory => './lib' },
 514         [ 'dbi:Pg:dbname="foo"','postgres','',
 515           { loader_class => 'MyLoader' } # optionally
 516         ],
 517     );
 518
 519 The last hashref in the C<\@connect_info> is checked for loader arguments such
 520 as C<loader_options> and C<loader_class>, see L</connection> for more details.
 521
 522 =cut
 523
 524 sub make_schema_at {
 525     my ($target, $opts, $connect_info) = @_;
 526
 527     {
 528         no strict 'refs';
 529         @{$target . '::ISA'} = qw/DBIx::Class::Schema::Loader/;
 530     }
 531
 532     $target->_loader_invoked(0);
 533
 534     $target->loader_options($opts);
 535
 536     my $temp_schema = $target->connect(@$connect_info);
 537
 538     $target->storage($temp_schema->storage);
 539     $target->storage->set_schema($target);
 540
 541     return $target;
 542 }
 543
 544 =head2 rescan
 545
 546 =over 4
 547
 548 =item Return Value: @new_monikers
 549
 550 =back
 551
 552 Re-scans the database for newly added tables since the initial
 553 load, and adds them to the schema at runtime, including relationships,
 554 etc.  Does not process drops or changes.
 555
 556 Returns a list of the new monikers added.
 557
 558 =cut
 559
 560 sub rescan { my $self = shift; $self->loader->rescan($self) }
 561
 562 =head2 naming
 563
 564 =over 4
 565
 566 =item Arguments: \%opts | $ver
 567
 568 =back
 569
 570 Controls the naming options for backward compatibility, see
 571 L<DBIx::Class::Schema::Loader::Base/naming> for details.
 572
 573 To upgrade a dynamic schema, use:
 574
 575     __PACKAGE__->naming('current');
 576
 577 Can be imported into your dump script and called as a function as well:
 578
 579     naming('v4');
 580
 581 =head2 use_namespaces
 582
 583 =over 4
 584
 585 =item Arguments: 1|0
 586
 587 =back
 588
 589 Controls the use_namespaces options for backward compatibility, see
 590 L<DBIx::Class::Schema::Loader::Base/use_namespaces> for details.
 591
 592 To upgrade a dynamic schema, use:
 593
 594     __PACKAGE__->use_namespaces(1);
 595
 596 Can be imported into your dump script and called as a function as well:
 597
 598     use_namespaces(1);
 599
 600 =head1 KNOWN ISSUES
 601
 602 =head2 Multiple Database Schemas
 603
 604 See L<DBIx::Class::Schema::Loader::Base/db_schema>.
 605
 606 =head1 ACKNOWLEDGEMENTS
 607
 608 Matt S Trout, all of the #dbix-class folks, and everyone who's ever sent
 609 in a bug report or suggestion.
 610
 611 Based on L<DBIx::Class::Loader> by Sebastian Riedel
 612
 613 Based upon the work of IKEBE Tomohiro
 614
 615 =head1 AUTHORS
 616
 617 Caelum: Rafael Kitover <rkitover@cpan.org>
 618
 619 Dag-Erling Smørgrav <des@des.no>
 620
 621 Matias E. Fernandez <mfernandez@pisco.ch>
 622
 623 SineSwiper: Brendan Byrd <byrd.b@insightcom.com>
 624
 625 TSUNODA Kazuya <drk@drk7.jp>
 626
 627 acmoore: Andrew Moore <amoore@cpan.org>
 628
 629 alnewkirk: Al Newkirk <awncorp@cpan.org>
 630
 631 andrewalker: André Walker <andre@andrewalker.net>
 632
 633 angelixd: Paul C. Mantz <pcmantz@cpan.org>
 634
 635 arc: Aaron Crane <arc@cpan.org>
 636
 637 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
 638
 639 ash: Ash Berlin <ash@cpan.org>
 640
 641 blblack: Brandon Black <blblack@gmail.com>
 642
 643 bphillips: Brian Phillips <bphillips@cpan.org>
 644
 645 btilly: Ben Tilly <btilly@gmail.com>
 646
 647 domm: Thomas Klausner <domm@plix.at>
 648
 649 gugu: Andrey Kostenko <a.kostenko@rambler-co.ru>
 650
 651 hobbs: Andrew Rodland <arodland@cpan.org>
 652
 653 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
 654
 655 jhannah: Jay Hannah <jay@jays.net>
 656
 657 jnap: John Napiorkowski <jjn1056@yahoo.com>
 658
 659 kane: Jos Boumans <kane@cpan.org>
 660
 661 mattp: Matt Phillips <mattp@cpan.org>
 662
 663 mephinet: Philipp Gortan <philipp.gortan@apa.at>
 664
 665 moritz: Moritz Lenz <moritz@faui2k3.org>
 666
 667 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
 668
 669 mstratman: Mark A. Stratman <stratman@gmail.com>
 670
 671 oalders: Olaf Alders <olaf@wundersolutions.com>
 672
 673 rbo: Robert Bohne <rbo@cpan.org>
 674
 675 rbuels: Robert Buels <rbuels@gmail.com>
 676
 677 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
 678
 679 schwern: Michael G. Schwern <mschwern@cpan.org>
 680
 681 spb: Stephen Bennett <spb@exherbo.org>
 682
 683 timbunce: Tim Bunce <timb@cpan.org>
 684
 685 waawaamilk: Nigel McNie <nigel@mcnie.name>
 686
 687 ... and lots of other folks. If we forgot you, please write the current
 688 maintainer or RT.
 689
 690 =head1 COPYRIGHT & LICENSE
 691
 692 Copyright (c) 2006 - 2015 by the aforementioned
 693 L<DBIx::Class::Schema::Loader/AUTHORS>.
 694
 695 This library is free software; you can redistribute it and/or modify it under
 696 the same terms as Perl itself.
 697
 698 =head1 SEE ALSO
 699
 700 L<DBIx::Class>, L<DBIx::Class::Manual::Intro>, L<DBIx::Class::Tutorial>,
 701 L<DBIx::Class::Schema::Loader::Base>
 702
 703 =cut
 704
 705 1;
 706 # vim:et sts=4 sw=4 tw=0: