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/;
   6 use base qw/Class::Data::Accessor/;
   7 use Carp;
   8 use UNIVERSAL::require;
   9 use Class::C3;
  10 use Data::Dump qw/ dump /;
  11
  12 # Always remember to do all digits for the version even if they're 0
  13 # i.e. first release of 0.XX *must* be 0.XX000. This avoids fBSD ports
  14 # brain damage and presumably various other packaging systems too
  15 our $VERSION = '0.02999_10';
  16
  17 __PACKAGE__->mk_classaccessor('dump_to_dir');
  18 __PACKAGE__->mk_classaccessor('loader');
  19 __PACKAGE__->mk_classaccessor('_loader_args');
  20
  21 =head1 NAME
  22
  23 DBIx::Class::Schema::Loader - Dynamic definition of a DBIx::Class::Schema
  24
  25 =head1 SYNOPSIS
  26
  27   package My::Schema;
  28   use base qw/DBIx::Class::Schema::Loader/;
  29
  30   __PACKAGE__->loader_options(
  31       relationships           => 1,
  32       constraint              => '^foo.*',
  33       # debug                 => 1,
  34   );
  35
  36   # in seperate application code ...
  37
  38   use My::Schema;
  39
  40   my $schema1 = My::Schema->connect( $dsn, $user, $password, $attrs);
  41   # -or-
  42   my $schema1 = "My::Schema"; $schema1->connection(as above);
  43 =head1 DESCRIPTION
  44 DBIx::Class::Schema::Loader automates the definition of a
  45 L<DBIx::Class::Schema> by scanning database table definitions and
  46 setting up the columns and primary keys.
  47
  48 DBIx::Class::Schema::Loader currently supports DBI for MySQL,
  49 Postgres, SQLite and DB2.
  50
  51 See L<DBIx::Class::Schema::Loader::DBI::Writing> for notes on writing
  52 your own vendor-specific subclass for an unsupported DBD driver.
  53
  54 This module requires L<DBIx::Class> 0.06 or later, and obsoletes
  55 the older L<DBIx::Class::Loader>.
  56
  57 This module is designed more to get you up and running quickly against
  58 an existing database, or to be effective for simple situations, rather
  59 than to be what you use in the long term for a complex database/project.
  60
  61 That being said, transitioning your code from a Schema generated by this
  62 module to one that doesn't use this module should be straightforward and
  63 painless (as long as you're not using any methods that are now deprecated
  64 in this document), so don't shy away from it just for fears of the
  65 transition down the road.
  66
  67 =head1 METHODS
  68
  69 =head2 loader_options
  70
  71 Example in Synopsis above demonstrates a few common arguments.  For
  72 detailed information on all of the arguments, most of which are
  73 only useful in fairly complex scenarios, see the
  74 L<DBIx::Class::Schema::Loader::Base> documentation.
  75
  76 This method is *required*, for backwards compatibility reasons.  If
  77 you do not wish to change any options, just call it with an empty
  78 argument list during schema class initialization.
  79
  80 =cut
  81
  82 sub loader_options {
  83     my $self = shift;
  84
  85     my %args;
  86     if(ref $_[0] eq 'HASH') {
  87         %args = %{$_[0]};
  88     }
  89     else {
  90         %args = @_;
  91     }
  92
  93     my $class = ref $self || $self;
  94     $args{schema} = $self;
  95     $args{schema_class} = $class;
  96     $self->_loader_args(\%args);
  97     $self->_invoke_loader if $self->storage && !$class->loader;
  98
  99     $self;
 100 }
 101
 102 sub _invoke_loader {
 103     my $self = shift;
 104     my $class = ref $self || $self;
 105
 106     $self->_loader_args->{dump_directory} ||= $self->dump_to_dir;
 107
 108     # XXX this only works for relative storage_type, like ::DBI ...
 109     my $impl = "DBIx::Class::Schema::Loader" . $self->storage_type;
 110     $impl->require or
 111       croak qq/Could not load storage_type loader "$impl": / .
 112             qq/"$UNIVERSAL::require::ERROR"/;
 113
 114     # XXX in the future when we get rid of ->loader, the next two
 115     # lines can be replaced by "$impl->new(%{$self->_loader_args})->load;"
 116     $class->loader($impl->new(%{$self->_loader_args}));
 117     $class->loader->load;
 118
 119
 120     $self;
 121 }
 122
 123 =head2 connection
 124
 125 See L<DBIx::Class::Schema>.  Our local override here is to
 126 hook in the main functionality of the loader, which occurs at the time
 127 the connection is specified for a given schema class/object.
 128
 129 =cut
 130
 131 sub connection {
 132     my $self = shift->next::method(@_);
 133
 134     my $class = ref $self || $self;
 135     $self->_invoke_loader if $self->_loader_args && !$class->loader;
 136
 137     return $self;
 138 }
 139
 140 =head2 clone
 141
 142 See L<DBIx::Class::Schema>.  Our local override here is to
 143 make sure cloned schemas can still be loaded at runtime by
 144 copying and altering a few things here.
 145
 146 =cut
 147
 148 sub clone {
 149     my $self = shift;
 150
 151     my $clone = $self->next::method(@_);
 152
 153     $clone->_loader_args($self->_loader_args);
 154     $clone->_loader_args->{schema} = $clone;
 155
 156     $clone;
 157 }
 158
 159 =head2 dump_to_dir
 160
 161 Argument: directory name.
 162
 163 Calling this as a class method on either L<DBIx::Class::Schema::Loader>
 164 or any derived schema class will cause all affected schemas to dump
 165 manual versions of themselves to the named directory when they are
 166 loaded.  In order to be effective, this must be set before defining a
 167 connection on this schema class or any derived object (as the loading
 168 happens at connection time, and only once per class).
 169
 170 See L<DBIx::Class::Schema::Loader::Base/dump_directory> for more
 171 details on the dumping mechanism.
 172
 173 This can also be set at module import time via the import option
 174 C<dump_to_dir:/foo/bar> to L<DBIx::Class::Schema::Loader>, where
 175 C</foo/bar> is the target directory.
 176
 177 Examples:
 178
 179     # My::Schema isa DBIx::Class::Schema::Loader, and has connection info
 180     #   hardcoded in the class itself:
 181     perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1
 182
 183     # Same, but no hard-coded connection, so we must provide one:
 184     perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)'
 185
 186     # Or as a class method, as long as you get it done *before* defining a
 187     #  connection on this schema class or any derived object:
 188     use My::Schema;
 189     My::Schema->dump_to_dir('/foo/bar');
 190     My::Schema->connection(........);
 191
 192     # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all
 193     #   derived schemas
 194     use My::Schema;
 195     use My::OtherSchema;
 196     DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar');
 197     My::Schema->connection(.......);
 198     My::OtherSchema->connection(.......);
 199
 200     # Another alternative to the above:
 201     use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |;
 202     use My::Schema;
 203     use My::OtherSchema;
 204     My::Schema->connection(.......);
 205     My::OtherSchema->connection(.......);
 206
 207 =cut
 208
 209 sub import {
 210     my $self = shift;
 211     return if !@_;
 212     foreach my $opt (@_) {
 213         if($opt =~ m{^dump_to_dir:(.*)$}) {
 214             $self->dump_to_dir($1)
 215         }
 216         elsif($opt eq 'make_schema_at') {
 217             no strict 'refs';
 218             my $cpkg = (caller)[0];
 219             *{"${cpkg}::make_schema_at"} = \&make_schema_at;
 220         }
 221     }
 222 }
 223
 224 =head2 make_schema_at
 225
 226 This simple function allows one to create a Loader-based schema
 227 in-memory on the fly without any on-disk class files of any
 228 kind.  When used with the C<dump_directory> option, you can
 229 use this to generate a rought draft manual schema from a dsn
 230 without the intermediate step of creating a physical Loader-based
 231 schema class.
 232
 233 This function can be exported/imported by the normal means, as
 234 illustrated in these Examples:
 235
 236     # Simple example...
 237     use DBIx::Class::Schema::Loader qw/ make_schema_at /;
 238     make_schema_at(
 239         'New::Schema::Name',
 240         { relationships => 1, debug => 1 },
 241         [ 'dbi:Pg:dbname="foo"','postgres' ],
 242     );
 243
 244     # Complex: dump loaded schema to disk, all from the commandline:
 245     perl -MDBIx::Class::Schema::Loader=make_schema_at,dump_to_dir:./lib -e 'make_schema_at("New::Schema::Name", { relationships => 1 }, [ 'dbi:Pg:dbname="foo"','postgres' ])'
 246
 247     # Same, but inside a script, and using a different way to specify the
 248     # dump directory:
 249     use DBIx::Class::Schema::Loader qw/ make_schema_at /;
 250     make_schema_at(
 251         'New::Schema::Name',
 252         { relationships => 1, debug => 1, dump_directory => './lib' },
 253         [ 'dbi:Pg:dbname="foo"','postgres' ],
 254     );
 255
 256 =cut
 257
 258 sub make_schema_at {
 259     my ($target, $opts, $connect_info) = @_;
 260
 261     my $opts_dumped = dump($opts);
 262     my $cinfo_dumped = dump(@$connect_info);
 263     eval qq|
 264         package $target;
 265         use base qw/DBIx::Class::Schema::Loader/;
 266         __PACKAGE__->loader_options($opts_dumped);
 267         __PACKAGE__->connection($cinfo_dumped);
 268     |;
 269 }
 270
 271 =head1 EXAMPLE
 272
 273 Using the example in L<DBIx::Class::Manual::ExampleSchema> as a basis
 274 replace the DB::Main with the following code:
 275
 276   package DB::Main;
 277
 278   use base qw/DBIx::Class::Schema::Loader/;
 279
 280   __PACKAGE__->loader_options(
 281       relationships => 1,
 282       debug         => 1,
 283   );
 284   __PACKAGE__->connection('dbi:SQLite:example.db');
 285
 286   1;
 287
 288 and remove the Main directory tree (optional).  Every thing else
 289 should work the same
 290
 291 =head1 DEPRECATED METHODS
 292
 293 You don't need to read anything in this section unless you're upgrading
 294 code that was written against pre-0.03 versions of this module.  This
 295 version is intended to be backwards-compatible with pre-0.03 code, but
 296 will issue warnings about your usage of deprecated features/methods.
 297
 298 =head2 load_from_connection
 299
 300 This deprecated method is now roughly an alias for L</loader_options>.
 301
 302 In the past it was a common idiom to invoke this method
 303 after defining a connection on the schema class.  That usage is now
 304 deprecated.  The correct way to do things from now forward is to
 305 always do C<loader_options> on the class before C<connect> or
 306 C<connection> is invoked on the class or any derived object.
 307
 308 This method *will* dissappear in a future version.
 309
 310 For now, using this method will invoke the legacy behavior for
 311 backwards compatibility, and merely emit a warning about upgrading
 312 your code.
 313
 314 It also reverts the default inflection scheme to
 315 use L<Lingua::EN::Inflect> just like pre-0.03 versions of this
 316 module did.
 317
 318 You can force these legacy inflections with the
 319 option C<legacy_default_inflections>, even after switch over
 320 to the preferred L</loader_options> way of doing things.
 321
 322 See the source of this method for more details.
 323
 324 =cut
 325
 326 sub load_from_connection {
 327     my ($self, %args) = @_;
 328     warn 'load_from_connection deprecated, please [re-]read the'
 329       . ' [new] DBIx::Class::Schema::Loader documentation';
 330
 331     # Support the old connect_info / dsn / etc args...
 332     $args{connect_info} = [
 333         delete $args{dsn},
 334         delete $args{user},
 335         delete $args{password},
 336         delete $args{options},
 337     ] if $args{dsn};
 338
 339     $self->connection(@{delete $args{connect_info}})
 340         if $args{connect_info};
 341
 342     $self->loader_options('legacy_default_inflections' => 1, %args);
 343 }
 344
 345 =head2 loader
 346
 347 This is an accessor in the generated Schema class for accessing
 348 the L<DBIx::Class::Schema::Loader::Base> -based loader object
 349 that was used during construction.  See the
 350 L<DBIx::Class::Schema::Loader::Base> docs for more information
 351 on the available loader methods there.
 352
 353 This accessor is deprecated.  Do not use it.  Anything you can
 354 get from C<loader>, you can get via the normal L<DBIx::Class::Schema>
 355 methods, and your code will be more robust and forward-thinking
 356 for doing so.
 357
 358 If you're already using C<loader> in your code, make an effort
 359 to get rid of it.  If you think you've found a situation where it
 360 is neccesary, let me know and we'll see what we can do to remedy
 361 that situation.
 362
 363 In some future version, this accessor *will* disappear.  It was
 364 apparently quite a design/API mistake to ever have exposed it to
 365 user-land in the first place, all things considered.
 366
 367 =head1 KNOWN ISSUES
 368
 369 =head2 Multiple Database Schemas
 370
 371 Currently the loader is limited to working within a single schema
 372 (using the database vendors' definition of "schema").  If you
 373 have a multi-schema database with inter-schema relationships (which
 374 is easy to do in Postgres or DB2 for instance), you only get to
 375 automatically load the tables of one schema, and any relationships
 376 to tables in other schemas will be silently ignored.
 377
 378 At some point in the future, an intelligent way around this might be
 379 devised, probably by allowing the C<db_schema> option to be an
 380 arrayref of schemas to load, or perhaps even offering schema
 381 constraint/exclusion options just like the table ones.
 382
 383 In "normal" L<DBIx::Class::Schema> usage, manually-defined
 384 source classes and relationships have no problems crossing vendor schemas.
 385
 386 =head1 AUTHOR
 387
 388 Brandon Black, C<blblack@gmail.com>
 389
 390 Based on L<DBIx::Class::Loader> by Sebastian Riedel
 391
 392 Based upon the work of IKEBE Tomohiro
 393
 394 =head1 THANK YOU
 395
 396 Adam Anderson, Andy Grundman, Autrijus Tang, Dan Kubb, David Naughton,
 397 Randal Schwartz, Simon Flack, Matt S Trout, everyone on #dbix-class, and
 398 all the others who've helped.
 399
 400 =head1 LICENSE
 401
 402 This library is free software; you can redistribute it and/or modify it under
 403 the same terms as Perl itself.
 404
 405 =head1 SEE ALSO
 406
 407 L<DBIx::Class>, L<DBIx::Class::Manual::ExampleSchema>
 408
 409 =cut
 410
 411 1;