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