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