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