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 UNIVERSAL::require;
   8 use Class::C3;
   9 use Scalar::Util qw/ weaken /;
  10
  11 # Always remember to do all digits for the version even if they're 0
  12 # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
  13 # brain damage and presumably various other packaging systems too
  14 our $VERSION = '0.04999_05';
  15
  16 __PACKAGE__->mk_classaccessor('_loader_args' => {});
  17 __PACKAGE__->mk_classaccessors(qw/dump_to_dir _loader_invoked _loader loader_class/);
  18
  19 =head1 NAME
  20
  21 DBIx::Class::Schema::Loader - Dynamic definition of a DBIx::Class::Schema
  22
  23 =head1 SYNOPSIS
  24
  25   package My::Schema;
  26   use base qw/DBIx::Class::Schema::Loader/;
  27
  28   __PACKAGE__->loader_options(
  29       constraint              => '^foo.*',
  30       # debug                 => 1,
  31   );
  32
  33   # in seperate application code ...
  34
  35   use My::Schema;
  36
  37   my $schema1 = My::Schema->connect( $dsn, $user, $password, $attrs);
  38   # -or-
  39   my $schema1 = "My::Schema"; $schema1->connection(as above);
  40
  41 =head1 DESCRIPTION
  42
  43 DBIx::Class::Schema::Loader automates the definition of a
  44 L<DBIx::Class::Schema> by scanning database table definitions and
  45 setting up the columns, primary keys, and relationships.
  46
  47 DBIx::Class::Schema::Loader currently supports only the DBI storage type.
  48 It has explicit support for L<DBD::Pg>, L<DBD::mysql>, L<DBD::DB2>,
  49 L<DBD::SQLite>, and L<DBD::Oracle>.  Other DBI drivers may function to
  50 a greater or lesser degree with this loader, depending on how much of the
  51 DBI spec they implement, and how standard their implementation is.
  52
  53 Patches to make other DBDs work correctly welcome.
  54
  55 See L<DBIx::Class::Schema::Loader::DBI::Writing> for notes on writing
  56 your own vendor-specific subclass for an unsupported DBD driver.
  57
  58 This module requires L<DBIx::Class> 0.07006 or later, and obsoletes
  59 the older L<DBIx::Class::Loader>.
  60
  61 This module is designed more to get you up and running quickly against
  62 an existing database, or to be effective for simple situations, rather
  63 than to be what you use in the long term for a complex database/project.
  64
  65 That being said, transitioning your code from a Schema generated by this
  66 module to one that doesn't use this module should be straightforward and
  67 painless, so don't shy away from it just for fears of the transition down
  68 the road.
  69
  70 =head1 METHODS
  71
  72 =head2 loader_class
  73
  74 Set the loader class to be instantiated when L</connection> is called.
  75 If the classname starts with "::", "DBIx::Class::Schema::Loader" is
  76 prepended. Defaults to L<DBIx::Class::Schema/storage_type> (which must
  77 start with "::" when using L<DBIx::Class::Schema::Loader>).
  78
  79 This is mostly useful for subclassing existing loaders or in conjunction
  80 with L</dump_to_dir>.
  81
  82 =head2 loader_options
  83
  84 Example in Synopsis above demonstrates a few common arguments.  For
  85 detailed information on all of the arguments, most of which are
  86 only useful in fairly complex scenarios, see the
  87 L<DBIx::Class::Schema::Loader::Base> documentation.
  88
  89 If you intend to use C<loader_options>, you must call
  90 C<loader_options> before any connection is made, or embed the
  91 C<loader_options> in the connection information itself as shown
  92 below.  Setting C<loader_options> after the connection has
  93 already been made is useless.
  94
  95 =cut
  96
  97 sub loader_options {
  98     my $self = shift;
  99
 100     my %args = (ref $_[0] eq 'HASH') ? %{$_[0]} : @_;
 101     $self->_loader_args(\%args);
 102
 103     $self;
 104 }
 105
 106 sub _invoke_loader {
 107     my $self = shift;
 108     my $class = ref $self || $self;
 109
 110     my $args = $self->_loader_args;
 111
 112     # set up the schema/schema_class arguments
 113     $args->{schema} = $self;
 114     $args->{schema_class} = $class;
 115     weaken($args->{schema}) if ref $self;
 116     $args->{dump_directory} ||= $self->dump_to_dir;
 117
 118     # XXX this only works for relative storage_type, like ::DBI ...
 119     my $impl = $self->loader_class
 120       || "DBIx::Class::Schema::Loader" . $self->storage_type;
 121     $impl = "DBIx::Class::Schema::Loader${impl}" if $impl =~ /^::/;
 122     $impl->require or
 123       croak qq/Could not load storage_type loader "$impl": / .
 124             qq/"$UNIVERSAL::require::ERROR"/;
 125
 126     $self->_loader($impl->new(%$args));
 127     $self->_loader->load;
 128     $self->_loader_invoked(1);
 129
 130     $self;
 131 }
 132
 133 =head2 connection
 134
 135 See L<DBIx::Class::Schema> for basic usage.
 136
 137 If the final argument is a hashref, and it contains the keys C<loader_options>
 138 or C<loader_class>, those keys will be deleted, and their values value will be
 139 used for the loader options or class, respectively, just as if set via the
 140 L</loader_options> or L</loader_class> methods above.
 141
 142 The actual auto-loading operation (the heart of this module) will be invoked
 143 as soon as the connection information is defined.
 144
 145 =cut
 146
 147 sub connection {
 148     my $self = shift;
 149
 150     if($_[-1] && ref $_[-1] eq 'HASH') {
 151         for my $option (qw/ loader_class loader_options /) {
 152             if(my $value = delete $_[-1]->{$option}) {
 153                 $self->$option($value);
 154             }
 155         }
 156         pop @_ if !keys %{$_[-1]};
 157     }
 158
 159     $self = $self->next::method(@_);
 160
 161     my $class = ref $self || $self;
 162     if(!$class->_loader_invoked) {
 163         $self->_invoke_loader
 164     }
 165
 166     return $self;
 167 }
 168
 169 =head2 clone
 170
 171 See L<DBIx::Class::Schema>.
 172
 173 =cut
 174
 175 sub clone {
 176     my $self = shift;
 177
 178     my $clone = $self->next::method(@_);
 179
 180     if($clone->_loader_args) {
 181         $clone->_loader_args->{schema} = $clone;
 182         weaken($clone->_loader_args->{schema});
 183     }
 184
 185     $clone;
 186 }
 187
 188 =head2 dump_to_dir
 189
 190 Argument: directory name.
 191
 192 Calling this as a class method on either L<DBIx::Class::Schema::Loader>
 193 or any derived schema class will cause all affected schemas to dump
 194 manual versions of themselves to the named directory when they are
 195 loaded.  In order to be effective, this must be set before defining a
 196 connection on this schema class or any derived object (as the loading
 197 happens as soon as both a connection and loader_options are set, and
 198 only once per class).
 199
 200 See L<DBIx::Class::Schema::Loader::Base/dump_directory> for more
 201 details on the dumping mechanism.
 202
 203 This can also be set at module import time via the import option
 204 C<dump_to_dir:/foo/bar> to L<DBIx::Class::Schema::Loader>, where
 205 C</foo/bar> is the target directory.
 206
 207 Examples:
 208
 209     # My::Schema isa DBIx::Class::Schema::Loader, and has connection info
 210     #   hardcoded in the class itself:
 211     perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1
 212
 213     # Same, but no hard-coded connection, so we must provide one:
 214     perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)'
 215
 216     # Or as a class method, as long as you get it done *before* defining a
 217     #  connection on this schema class or any derived object:
 218     use My::Schema;
 219     My::Schema->dump_to_dir('/foo/bar');
 220     My::Schema->connection(........);
 221
 222     # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all
 223     #   derived schemas
 224     use My::Schema;
 225     use My::OtherSchema;
 226     DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar');
 227     My::Schema->connection(.......);
 228     My::OtherSchema->connection(.......);
 229
 230     # Another alternative to the above:
 231     use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |;
 232     use My::Schema;
 233     use My::OtherSchema;
 234     My::Schema->connection(.......);
 235     My::OtherSchema->connection(.......);
 236
 237 =cut
 238
 239 sub import {
 240     my $self = shift;
 241     return if !@_;
 242     foreach my $opt (@_) {
 243         if($opt =~ m{^dump_to_dir:(.*)$}) {
 244             $self->dump_to_dir($1)
 245         }
 246         elsif($opt eq 'make_schema_at') {
 247             no strict 'refs';
 248             my $cpkg = (caller)[0];
 249             *{"${cpkg}::make_schema_at"} = \&make_schema_at;
 250         }
 251     }
 252 }
 253
 254 =head2 make_schema_at
 255
 256 This simple function allows one to create a Loader-based schema
 257 in-memory on the fly without any on-disk class files of any
 258 kind.  When used with the C<dump_directory> option, you can
 259 use this to generate a rough draft manual schema from a dsn
 260 without the intermediate step of creating a physical Loader-based
 261 schema class.
 262
 263 The return value is the input class name.
 264
 265 This function can be exported/imported by the normal means, as
 266 illustrated in these Examples:
 267
 268     # Simple example, creates as a new class 'New::Schema::Name' in
 269     #  memory in the running perl interpreter.
 270     use DBIx::Class::Schema::Loader qw/ make_schema_at /;
 271     make_schema_at(
 272         'New::Schema::Name',
 273         { debug => 1 },
 274         [ 'dbi:Pg:dbname="foo"','postgres' ],
 275     );
 276
 277     # Complex: dump loaded schema to disk, all from the commandline:
 278     perl -MDBIx::Class::Schema::Loader=make_schema_at,dump_to_dir:./lib -e 'make_schema_at("New::Schema::Name", { debug => 1 }, [ "dbi:Pg:dbname=foo","postgres" ])'
 279
 280     # Same, but inside a script, and using a different way to specify the
 281     # dump directory:
 282     use DBIx::Class::Schema::Loader qw/ make_schema_at /;
 283     make_schema_at(
 284         'New::Schema::Name',
 285         { debug => 1, dump_directory => './lib' },
 286         [ 'dbi:Pg:dbname="foo"','postgres' ],
 287     );
 288
 289 =cut
 290
 291 sub make_schema_at {
 292     my ($target, $opts, $connect_info) = @_;
 293
 294     {
 295         no strict 'refs';
 296         @{$target . '::ISA'} = qw/DBIx::Class::Schema::Loader/;
 297     }
 298
 299     $target->loader_options($opts);
 300     $target->connection(@$connect_info);
 301 }
 302
 303 =head2 rescan
 304
 305 Re-scans the database for newly added tables since the initial
 306 load, and adds them to the schema at runtime, including relationships,
 307 etc.  Does not process drops or changes.
 308
 309 Returns a list of the new monikers added.
 310
 311 =cut
 312
 313 sub rescan { my $self = shift; $self->_loader->rescan($self) }
 314
 315 =head1 EXAMPLE
 316
 317 Using the example in L<DBIx::Class::Manual::ExampleSchema> as a basis
 318 replace the DB::Main with the following code:
 319
 320   package DB::Main;
 321
 322   use base qw/DBIx::Class::Schema::Loader/;
 323
 324   __PACKAGE__->loader_options(
 325       debug         => 1,
 326   );
 327   __PACKAGE__->connection('dbi:SQLite:example.db');
 328
 329   1;
 330
 331 and remove the Main directory tree (optional).  Every thing else
 332 should work the same
 333
 334 =head1 KNOWN ISSUES
 335
 336 =head2 Multiple Database Schemas
 337
 338 Currently the loader is limited to working within a single schema
 339 (using the database vendors' definition of "schema").  If you
 340 have a multi-schema database with inter-schema relationships (which
 341 is easy to do in PostgreSQL or DB2 for instance), you only get to
 342 automatically load the tables of one schema, and any relationships
 343 to tables in other schemas will be silently ignored.
 344
 345 At some point in the future, an intelligent way around this might be
 346 devised, probably by allowing the C<db_schema> option to be an
 347 arrayref of schemas to load.
 348
 349 In "normal" L<DBIx::Class::Schema> usage, manually-defined
 350 source classes and relationships have no problems crossing vendor schemas.
 351
 352 =head1 AUTHOR
 353
 354 Brandon Black, C<blblack@gmail.com>
 355
 356 Based on L<DBIx::Class::Loader> by Sebastian Riedel
 357
 358 Based upon the work of IKEBE Tomohiro
 359
 360 =head1 THANK YOU
 361
 362 Matt S Trout, all of the #dbix-class folks, and everyone who's ever sent
 363 in a bug report or suggestion.
 364
 365 =head1 LICENSE
 366
 367 This library is free software; you can redistribute it and/or modify it under
 368 the same terms as Perl itself.
 369
 370 =head1 SEE ALSO
 371
 372 L<DBIx::Class>, L<DBIx::Class::Manual::ExampleSchema>
 373
 374 =cut
 375
 376 1;