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