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 Carp::Clan qw/^DBIx::Class/;
   7 use mro 'c3';
   8 use Scalar::Util qw/ weaken /;
   9
  10 # Always remember to do all digits for the version even if they're 0
  11 # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
  12 # brain damage and presumably various other packaging systems too
  13 our $VERSION = '0.07010';
  14
  15 __PACKAGE__->mk_group_accessors('inherited', qw/
  16                                 _loader_args
  17                                 dump_to_dir
  18                                 _loader_invoked
  19                                 _loader
  20                                 loader_class
  21                                 naming
  22                                 use_namespaces
  23 /);
  24 __PACKAGE__->_loader_args({});
  25
  26 =head1 NAME
  27
  28 DBIx::Class::Schema::Loader - Dynamic definition of a DBIx::Class::Schema
  29
  30 =head1 SYNOPSIS
  31
  32   ### use this module to generate a set of class files
  33
  34   # in a script
  35   use DBIx::Class::Schema::Loader qw/ make_schema_at /;
  36   make_schema_at(
  37       'My::Schema',
  38       { debug => 1,
  39         dump_directory => './lib',
  40       },
  41       [ 'dbi:Pg:dbname="foo"', 'myuser', 'mypassword',
  42          { loader_class => 'MyLoader' } # optionally
  43       ],
  44   );
  45
  46   # from the command line or a shell script with dbicdump (distributed
  47   # with this module).  Do `perldoc dbicdump` for usage.
  48   dbicdump -o dump_directory=./lib \
  49            -o debug=1 \
  50            My::Schema \
  51            'dbi:Pg:dbname=foo' \
  52            myuser \
  53            mypassword
  54
  55   ### or generate and load classes at runtime
  56   # note: this technique is not recommended
  57   # for use in production code
  58
  59   package My::Schema;
  60   use base qw/DBIx::Class::Schema::Loader/;
  61
  62   __PACKAGE__->loader_options(
  63       constraint              => '^foo.*',
  64       # debug                 => 1,
  65   );
  66
  67   #### in application code elsewhere:
  68
  69   use My::Schema;
  70
  71   my $schema1 = My::Schema->connect( $dsn, $user, $password, $attrs);
  72   # -or-
  73   my $schema1 = "My::Schema"; $schema1->connection(as above);
  74
  75 =head1 DESCRIPTION
  76
  77 DBIx::Class::Schema::Loader automates the definition of a
  78 L<DBIx::Class::Schema> by scanning database table definitions and
  79 setting up the columns, primary keys, and relationships.
  80
  81 See L<dbicdump> for the C<dbicdump> utility.
  82
  83 DBIx::Class::Schema::Loader currently supports only the DBI storage type.  It
  84 has explicit support for L<DBD::Pg>, L<DBD::mysql>, L<DBD::DB2>,
  85 L<DBD::SQLite>, L<DBD::Sybase> (for Sybase ASE and MSSSQL), L<DBD::ODBC> (for
  86 MSSQL) and L<DBD::Oracle>.  Other DBI drivers may function to a greater or
  87 lesser degree with this loader, depending on how much of the DBI spec they
  88 implement, and how standard their implementation is.
  89
  90 Patches to make other DBDs work correctly welcome.
  91
  92 See L<DBIx::Class::Schema::Loader::DBI::Writing> for notes on writing
  93 your own vendor-specific subclass for an unsupported DBD driver.
  94
  95 This module requires L<DBIx::Class> 0.07006 or later, and obsoletes
  96 the older L<DBIx::Class::Loader>.
  97
  98 This module is designed more to get you up and running quickly against
  99 an existing database, or to be effective for simple situations, rather
 100 than to be what you use in the long term for a complex database/project.
 101
 102 That being said, transitioning your code from a Schema generated by this
 103 module to one that doesn't use this module should be straightforward and
 104 painless, so don't shy away from it just for fears of the transition down
 105 the road.
 106
 107 =head1 METHODS
 108
 109 =head2 loader_class
 110
 111 =over 4
 112
 113 =item Argument: $loader_class
 114
 115 =back
 116
 117 Set the loader class to be instantiated when L</connection> is called.
 118 If the classname starts with "::", "DBIx::Class::Schema::Loader" is
 119 prepended. Defaults to L<DBIx::Class::Schema/storage_type> (which must
 120 start with "::" when using L<DBIx::Class::Schema::Loader>).
 121
 122 This is mostly useful for subclassing existing loaders or in conjunction
 123 with L</dump_to_dir>.
 124
 125 =head2 loader_options
 126
 127 =over 4
 128
 129 =item Argument: \%loader_options
 130
 131 =back
 132
 133 Example in Synopsis above demonstrates a few common arguments.  For
 134 detailed information on all of the arguments, most of which are
 135 only useful in fairly complex scenarios, see the
 136 L<DBIx::Class::Schema::Loader::Base> documentation.
 137
 138 If you intend to use C<loader_options>, you must call
 139 C<loader_options> before any connection is made, or embed the
 140 C<loader_options> in the connection information itself as shown
 141 below.  Setting C<loader_options> after the connection has
 142 already been made is useless.
 143
 144 =cut
 145
 146 sub loader_options {
 147     my $self = shift;
 148
 149     my %args = (ref $_[0] eq 'HASH') ? %{$_[0]} : @_;
 150     $self->_loader_args(\%args);
 151
 152     $self;
 153 }
 154
 155 sub _invoke_loader {
 156     my $self = shift;
 157     my $class = ref $self || $self;
 158
 159     my $args = $self->_loader_args;
 160
 161     # set up the schema/schema_class arguments
 162     $args->{schema} = $self;
 163     $args->{schema_class} = $class;
 164     weaken($args->{schema}) if ref $self;
 165     $args->{dump_directory} ||= $self->dump_to_dir;
 166     $args->{naming} = $self->naming if $self->naming;
 167     $args->{use_namespaces} = $self->use_namespaces if $self->use_namespaces;
 168
 169     # XXX this only works for relative storage_type, like ::DBI ...
 170     my $loader_class = $self->loader_class;
 171     if ($loader_class) {
 172         $loader_class = "DBIx::Class::Schema::Loader${loader_class}" if $loader_class =~ /^::/;
 173         $args->{loader_class} = $loader_class;
 174     };
 175
 176     my $impl = $loader_class || "DBIx::Class::Schema::Loader" . $self->storage_type;
 177     eval { $self->ensure_class_loaded($impl) };
 178     croak qq/Could not load loader_class "$impl": "$@"/ if $@;
 179
 180     $self->_loader($impl->new(%$args));
 181     $self->_loader->load;
 182     $self->_loader_invoked(1);
 183
 184     $self;
 185 }
 186
 187 =head2 connection
 188
 189 =over 4
 190
 191 =item Arguments: @args
 192
 193 =item Return Value: $new_schema
 194
 195 =back
 196
 197 See L<DBIx::Class::Schema/connection> for basic usage.
 198
 199 If the final argument is a hashref, and it contains the keys C<loader_options>
 200 or C<loader_class>, those keys will be deleted, and their values value will be
 201 used for the loader options or class, respectively, just as if set via the
 202 L</loader_options> or L</loader_class> methods above.
 203
 204 The actual auto-loading operation (the heart of this module) will be invoked
 205 as soon as the connection information is defined.
 206
 207 =cut
 208
 209 sub connection {
 210     my $self = shift;
 211
 212     if($_[-1] && ref $_[-1] eq 'HASH') {
 213         for my $option (qw/ loader_class loader_options result_base_class schema_base_class/) {
 214             if(my $value = delete $_[-1]->{$option}) {
 215                 $self->$option($value);
 216             }
 217         }
 218         pop @_ if !keys %{$_[-1]};
 219     }
 220
 221     $self = $self->next::method(@_);
 222
 223     my $class = ref $self || $self;
 224     if(!$class->_loader_invoked) {
 225         $self->_invoke_loader
 226     }
 227
 228     return $self;
 229 }
 230
 231 =head2 clone
 232
 233 See L<DBIx::Class::Schema/clone>.
 234
 235 =cut
 236
 237 sub clone {
 238     my $self = shift;
 239
 240     my $clone = $self->next::method(@_);
 241
 242     if($clone->_loader_args) {
 243         $clone->_loader_args->{schema} = $clone;
 244         weaken($clone->_loader_args->{schema});
 245     }
 246
 247     $clone;
 248 }
 249
 250 =head2 dump_to_dir
 251
 252 =over 4
 253
 254 =item Argument: $directory
 255
 256 =back
 257
 258 Calling this as a class method on either L<DBIx::Class::Schema::Loader>
 259 or any derived schema class will cause all schemas to dump
 260 manual versions of themselves to the named directory when they are
 261 loaded.  In order to be effective, this must be set before defining a
 262 connection on this schema class or any derived object (as the loading
 263 happens as soon as both a connection and loader_options are set, and
 264 only once per class).
 265
 266 See L<DBIx::Class::Schema::Loader::Base/dump_directory> for more
 267 details on the dumping mechanism.
 268
 269 This can also be set at module import time via the import option
 270 C<dump_to_dir:/foo/bar> to L<DBIx::Class::Schema::Loader>, where
 271 C</foo/bar> is the target directory.
 272
 273 Examples:
 274
 275     # My::Schema isa DBIx::Class::Schema::Loader, and has connection info
 276     #   hardcoded in the class itself:
 277     perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1
 278
 279     # Same, but no hard-coded connection, so we must provide one:
 280     perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)'
 281
 282     # Or as a class method, as long as you get it done *before* defining a
 283     #  connection on this schema class or any derived object:
 284     use My::Schema;
 285     My::Schema->dump_to_dir('/foo/bar');
 286     My::Schema->connection(........);
 287
 288     # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all
 289     #   derived schemas
 290     use My::Schema;
 291     use My::OtherSchema;
 292     DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar');
 293     My::Schema->connection(.......);
 294     My::OtherSchema->connection(.......);
 295
 296     # Another alternative to the above:
 297     use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |;
 298     use My::Schema;
 299     use My::OtherSchema;
 300     My::Schema->connection(.......);
 301     My::OtherSchema->connection(.......);
 302
 303 =cut
 304
 305 sub import {
 306     my $self = shift;
 307
 308     return if !@_;
 309
 310     my $cpkg = (caller)[0];
 311
 312     foreach my $opt (@_) {
 313         if($opt =~ m{^dump_to_dir:(.*)$}) {
 314             $self->dump_to_dir($1)
 315         }
 316         elsif($opt eq 'make_schema_at') {
 317             no strict 'refs';
 318             *{"${cpkg}::make_schema_at"} = \&make_schema_at;
 319         }
 320         elsif($opt eq 'naming') {
 321             no strict 'refs';
 322             *{"${cpkg}::naming"} = sub { $self->naming(@_) };
 323         }
 324         elsif($opt eq 'use_namespaces') {
 325             no strict 'refs';
 326             *{"${cpkg}::use_namespaces"} = sub { $self->use_namespaces(@_) };
 327         }
 328     }
 329 }
 330
 331 =head2 make_schema_at
 332
 333 =over 4
 334
 335 =item Arguments: $schema_class_name, \%loader_options, \@connect_info
 336
 337 =item Return Value: $schema_class_name
 338
 339 =back
 340
 341 This function creates a DBIx::Class schema from an existing RDBMS
 342 schema.  With the C<dump_directory> option, generates a set of
 343 DBIx::Class classes from an existing database schema read from the
 344 given dsn.  Without a C<dump_directory>, creates schema classes in
 345 memory at runtime without generating on-disk class files.
 346
 347 For a complete list of supported loader_options, see
 348 L<DBIx::Class::Schema::Loader::Base>
 349
 350 The last hashref in the C<\@connect_info> can specify the L</loader_class>.
 351
 352 This function can be imported in the usual way, as illustrated in
 353 these Examples:
 354
 355     # Simple example, creates as a new class 'New::Schema::Name' in
 356     #  memory in the running perl interpreter.
 357     use DBIx::Class::Schema::Loader qw/ make_schema_at /;
 358     make_schema_at(
 359         'New::Schema::Name',
 360         { debug => 1 },
 361         [ 'dbi:Pg:dbname="foo"','postgres','',
 362           { loader_class => 'MyLoader' } # optionally
 363         ],
 364     );
 365
 366     # Inside a script, specifying a dump directory in which to write
 367     # class files
 368     use DBIx::Class::Schema::Loader qw/ make_schema_at /;
 369     make_schema_at(
 370         'New::Schema::Name',
 371         { debug => 1, dump_directory => './lib' },
 372         [ 'dbi:Pg:dbname="foo"','postgres','',
 373           { loader_class => 'MyLoader' } # optionally
 374         ],
 375     );
 376
 377 The last hashref in the C<\@connect_info> is checked for loader arguments such
 378 as C<loader_options> and C<loader_class>, see L</connection> for more details.
 379
 380 =cut
 381
 382 sub make_schema_at {
 383     my ($target, $opts, $connect_info) = @_;
 384
 385     {
 386         no strict 'refs';
 387         @{$target . '::ISA'} = qw/DBIx::Class::Schema::Loader/;
 388     }
 389
 390     eval { $target->_loader_invoked(0) };
 391
 392     $target->loader_options($opts);
 393     $target->connection(@$connect_info);
 394 }
 395
 396 =head2 rescan
 397
 398 =over 4
 399
 400 =item Return Value: @new_monikers
 401
 402 =back
 403
 404 Re-scans the database for newly added tables since the initial
 405 load, and adds them to the schema at runtime, including relationships,
 406 etc.  Does not process drops or changes.
 407
 408 Returns a list of the new monikers added.
 409
 410 =cut
 411
 412 sub rescan { my $self = shift; $self->_loader->rescan($self) }
 413
 414 =head2 naming
 415
 416 =over 4
 417
 418 =item Arguments: \%opts | $ver
 419
 420 =back
 421
 422 Controls the naming options for backward compatibility, see
 423 L<DBIx::Class::Schema::Loader::Base/naming> for details.
 424
 425 To upgrade a dynamic schema, use:
 426
 427     __PACKAGE__->naming('current');
 428
 429 Can be imported into your dump script and called as a function as well:
 430
 431     naming('v4');
 432
 433 =head2 use_namespaces
 434
 435 =over 4
 436
 437 =item Arguments: 1|0
 438
 439 =back
 440
 441 Controls the use_namespaces options for backward compatibility, see
 442 L<DBIx::Class::Schema::Loader::Base/use_namespaces> for details.
 443
 444 To upgrade a dynamic schema, use:
 445
 446     __PACKAGE__->use_namespaces(1);
 447
 448 Can be imported into your dump script and called as a function as well:
 449
 450     use_namespaces(1);
 451
 452 =head1 KNOWN ISSUES
 453
 454 =head2 Multiple Database Schemas
 455
 456 Currently the loader is limited to working within a single schema
 457 (using the underlying RDBMS's definition of "schema").  If you have a
 458 multi-schema database with inter-schema relationships (which is easy
 459 to do in PostgreSQL or DB2 for instance), you currently can only
 460 automatically load the tables of one schema, and relationships to
 461 tables in other schemas will be silently ignored.
 462
 463 At some point in the future, an intelligent way around this might be
 464 devised, probably by allowing the C<db_schema> option to be an
 465 arrayref of schemas to load.
 466
 467 In "normal" L<DBIx::Class::Schema> usage, manually-defined
 468 source classes and relationships have no problems crossing vendor schemas.
 469
 470 =head1 ACKNOWLEDGEMENTS
 471
 472 Matt S Trout, all of the #dbix-class folks, and everyone who's ever sent
 473 in a bug report or suggestion.
 474
 475 Based on L<DBIx::Class::Loader> by Sebastian Riedel
 476
 477 Based upon the work of IKEBE Tomohiro
 478
 479 =head1 AUTHOR
 480
 481 blblack: Brandon Black <blblack@gmail.com>
 482
 483 =head1 CONTRIBUTORS
 484
 485 ilmari: Dagfinn Ilmari MannsE<aring>ker <ilmari@ilmari.org>
 486
 487 arcanez: Justin Hunter <justin.d.hunter@gmail.com>
 488
 489 ash: Ash Berlin <ash@cpan.org>
 490
 491 Caelum: Rafael Kitover <rkitover@cpan.org>
 492
 493 TSUNODA Kazuya <drk@drk7.jp>
 494
 495 rbo: Robert Bohne <rbo@cpan.org>
 496
 497 ribasushi: Peter Rabbitson <ribasushi@cpan.org>
 498
 499 gugu: Andrey Kostenko <a.kostenko@rambler-co.ru>
 500
 501 jhannah: Jay Hannah <jay@jays.net>
 502
 503 rbuels: Robert Buels <rmb32@cornell.edu>
 504
 505 timbunce: Tim Bunce <timb@cpan.org>
 506
 507 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
 508
 509 mstratman: Mark A. Stratman <stratman@gmail.com>
 510
 511 kane: Jos Boumans <kane@cpan.org>
 512
 513 waawaamilk: Nigel McNie <nigel@mcnie.name>
 514
 515 acmoore: Andrew Moore <amoore@cpan.org>
 516
 517 bphillips: Brian Phillips <bphillips@cpan.org>
 518
 519 schwern: Michael G. Schwern <mschwern@cpan.org>
 520
 521 hobbs: Andrew Rodland <arodland@cpan.org>
 522
 523 domm: Thomas Klausner <domm@plix.at>
 524
 525 spb: Stephen Bennett <spb@exherbo.org>
 526
 527 Matias E. Fernandez <mfernandez@pisco.ch>
 528
 529 mstratman: Mark A. Stratman <stratman@gmail.com>
 530
 531 ... and lots of other folks. If we forgot you, please write the current
 532 maintainer or RT.
 533
 534 =head1 COPYRIGHT & LICENSE
 535
 536 Copyright (c) 2006 - 2009 by the aforementioned
 537 L<DBIx::Class::Schema::Loader/AUTHOR> and
 538 L<DBIx::Class::Schema::Loader/CONTRIBUTORS>.
 539
 540 This library is free software; you can redistribute it and/or modify it under
 541 the same terms as Perl itself.
 542
 543 =head1 SEE ALSO
 544
 545 L<DBIx::Class>, L<DBIx::Class::Manual::ExampleSchema>
 546
 547 =cut
 548
 549 1;
 550 # vim:et sts=4 sw=4 tw=0: