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
  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.02004';
  14
  15 __PACKAGE__->mk_classaccessor('loader');
  16
  17 =head1 NAME
  18
  19 DBIx::Class::Schema::Loader - Dynamic definition of a DBIx::Class::Schema
  20
  21 =head1 SYNOPSIS
  22
  23   package My::Schema;
  24   use base qw/DBIx::Class::Schema::Loader/;
  25
  26   sub _monikerize {
  27       my $name = shift;
  28       $name = join '', map ucfirst, split /[\W_]+/, lc $name;
  29       $name;
  30   }
  31
  32   __PACKAGE__->load_from_connection(
  33     connect_info            => [ "dbi:mysql:dbname",
  34                                  "root",
  35                                  "mypassword",
  36                                  { AutoCommit => 1 },
  37                                ],
  38     additional_classes      => [qw/DBIx::Class::Foo/],
  39     additional_base_classes => [qw/My::Stuff/],
  40     left_base_classes       => [qw/DBIx::Class::Bar/],
  41     components              => [qw/ResultSetManager/],
  42     resultset_components    => [qw/AlwaysRS/],
  43     constraint              => '^foo.*',
  44     relationships           => 1,
  45     options                 => { AutoCommit => 1 },
  46     inflect_map             => { child => 'children' },
  47     moniker_map             => \&_monikerize,
  48     debug                   => 1,
  49   );
  50
  51   # in seperate application code ...
  52
  53   use My::Schema;
  54
  55   my $schema1 = My::Schema->connect( $dsn, $user, $password, $attrs);
  56   # -or-
  57   my $schema1 = "My::Schema";
  58   # ^^ defaults to dsn/user/pass from load_from_connection()
  59
  60   # Get a list of the original (database) names of the tables that
  61   #  were loaded
  62   my @tables = $schema1->loader->tables;
  63
  64   # Get a hashref of table_name => 'TableName' table-to-moniker
  65   #   mappings.
  66   my $monikers = $schema1->loader->monikers;
  67
  68   # Get a hashref of table_name => 'My::Schema::TableName'
  69   #   table-to-classname mappings.
  70   my $classes = $schema1->loader->classes;
  71
  72   # Use the schema as per normal for DBIx::Class::Schema
  73   my $rs = $schema1->resultset($monikers->{foo_table})->search(...);
  74
  75 =head1 DESCRIPTION
  76
  77 DBIx::Class::Schema::Loader automates the definition of a
  78 DBIx::Class::Schema by scanning table schemas and setting up
  79 columns and primary keys.
  80
  81 DBIx::Class::Schema::Loader supports MySQL, Postgres, SQLite and DB2.  See
  82 L<DBIx::Class::Schema::Loader::Generic> for more, and
  83 L<DBIx::Class::Schema::Loader::Writing> for notes on writing your own
  84 db-specific subclass for an unsupported db.
  85
  86 This module requires L<DBIx::Class> 0.05 or later, and obsoletes
  87 L<DBIx::Class::Loader> for L<DBIx::Class> version 0.05 and later.
  88
  89 While on the whole, the bare table definitions are fairly straightforward,
  90 relationship creation is somewhat heuristic, especially in the choosing
  91 of relationship types, join types, and relationship names.  The relationships
  92 generated by this module will probably never be as well-defined as
  93 hand-generated ones.  Because of this, over time a complex project will
  94 probably wish to migrate off of L<DBIx::Class::Schema::Loader>.
  95
  96 It is designed more to get you up and running quickly against an existing
  97 database, or to be effective for simple situations, rather than to be what
  98 you use in the long term for a complex database/project.
  99
 100 That being said, transitioning your code from a Schema generated by this
 101 module to one that doesn't use this module should be straightforward and
 102 painless, so don't shy away from it just for fears of the transition down
 103 the road.
 104
 105 =head1 METHODS
 106
 107 =head2 load_from_connection
 108
 109 Example in Synopsis above demonstrates the available arguments.  For
 110 detailed information on the arguments, see the
 111 L<DBIx::Class::Schema::Loader::Generic> documentation.
 112
 113 =cut
 114
 115 # XXX this is DBI-specific, as it peers into the dsn to determine
 116 # the vendor class to use...
 117 sub load_from_connection {
 118     my ( $class, %args ) = @_;
 119
 120     my $dsn;
 121
 122     if($args{connect_info} && $args{connect_info}->[0]) {
 123         $dsn = $args{connect_info}->[0];
 124     }
 125     elsif($args{dsn}) {
 126         warn "dsn argument is deprecated, please use connect_info instead";
 127         $dsn = $args{dsn};
 128     }
 129     else {
 130         croak 'connect_info arrayref argument with valid '
 131               . 'first element is required';
 132     }
 133
 134     my ($driver) = $dsn =~ m/^dbi:(\w*?)(?:\((.*?)\))?:/i;
 135     $driver = 'SQLite' if $driver eq 'SQLite2';
 136     my $impl = "DBIx::Class::Schema::Loader::" . $driver;
 137
 138     $impl->require or
 139       croak qq/Couldn't require loader class "$impl",/ .
 140             qq/"$UNIVERSAL::require::ERROR"/;
 141
 142     $args{schema} = $class;
 143
 144     $class->loader($impl->new(%args));
 145     $class->loader->load;
 146 }
 147
 148 =head2 loader
 149
 150 This is an accessor in the generated Schema class for accessing
 151 the L<DBIx::Class::Schema::Loader::Generic> -based loader object
 152 that was used during construction.  See the
 153 L<DBIx::Class::Schema::Loader::Generic> docs for more information
 154 on the available loader methods there.
 155
 156 =head1 KNOWN BUGS
 157
 158 Aside from relationship definitions being less than ideal in general,
 159 this version is known not to handle the case of multiple relationships
 160 between the same pair of tables.  All of the relationship code will
 161 be overhauled on the way to 0.03, at which time that bug will be
 162 addressed.
 163
 164 =head1 AUTHOR
 165
 166 Brandon Black, C<blblack@gmail.com>
 167
 168 Based on L<DBIx::Class::Loader> by Sebastian Riedel
 169
 170 Based upon the work of IKEBE Tomohiro
 171
 172 =head1 THANK YOU
 173
 174 Adam Anderson, Andy Grundman, Autrijus Tang, Dan Kubb, David Naughton,
 175 Randal Schwartz, Simon Flack and all the others who've helped.
 176
 177 =head1 LICENSE
 178
 179 This library is free software; you can redistribute it and/or modify it under
 180 the same terms as Perl itself.
 181
 182 =head1 SEE ALSO
 183
 184 L<DBIx::Class>
 185
 186 =cut
 187
 188 1;