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