README

   1 NAME
   2     DBIx::Class::Schema::Loader - Dynamic definition of a
   3     DBIx::Class::Schema
   4
   5 SYNOPSIS
   6       ### use this module to generate a set of class files
   7
   8       # in a script
   9       use DBIx::Class::Schema::Loader qw/ make_schema_at /;
  10       make_schema_at(
  11           'My::Schema',
  12           { debug => 1,
  13             dump_directory => './lib',
  14           },
  15           [ 'dbi:Pg:dbname="foo"', 'myuser', 'mypassword' ],
  16       );
  17
  18       # from the command line or a shell script with dbicdump (distributed
  19       # with this module).  Do `perldoc dbicdump` for usage.
  20       dbicdump -o dump_directory=./lib \
  21                -o debug=1 \
  22                My::Schema \
  23                'dbi:Pg:dbname=foo' \
  24                myuser \
  25                mypassword
  26
  27       ### or generate and load classes at runtime
  28       # note: this technique is not recommended
  29       # for use in production code
  30
  31       package My::Schema;
  32       use base qw/DBIx::Class::Schema::Loader/;
  33
  34       __PACKAGE__->loader_options(
  35           constraint              => '^foo.*',
  36           # debug                 => 1,
  37       );
  38
  39       #### in application code elsewhere:
  40
  41       use My::Schema;
  42
  43       my $schema1 = My::Schema->connect( $dsn, $user, $password, $attrs);
  44       # -or-
  45       my $schema1 = "My::Schema"; $schema1->connection(as above);
  46
  47 DESCRIPTION
  48     DBIx::Class::Schema::Loader automates the definition of a
  49     DBIx::Class::Schema by scanning database table definitions and setting
  50     up the columns, primary keys, and relationships.
  51
  52     DBIx::Class::Schema::Loader currently supports only the DBI storage
  53     type. It has explicit support for DBD::Pg, DBD::mysql, DBD::DB2,
  54     DBD::SQLite, and DBD::Oracle. Other DBI drivers may function to a
  55     greater or lesser degree with this loader, depending on how much of the
  56     DBI spec they implement, and how standard their implementation is.
  57
  58     Patches to make other DBDs work correctly welcome.
  59
  60     See DBIx::Class::Schema::Loader::DBI::Writing for notes on writing your
  61     own vendor-specific subclass for an unsupported DBD driver.
  62
  63     This module requires DBIx::Class 0.07006 or later, and obsoletes the
  64     older DBIx::Class::Loader.
  65
  66     This module is designed more to get you up and running quickly against
  67     an existing database, or to be effective for simple situations, rather
  68     than to be what you use in the long term for a complex database/project.
  69
  70     That being said, transitioning your code from a Schema generated by this
  71     module to one that doesn't use this module should be straightforward and
  72     painless, so don't shy away from it just for fears of the transition
  73     down the road.
  74
  75 METHODS
  76   loader_class
  77     Argument: $loader_class
  78
  79     Set the loader class to be instantiated when "connection" is called. If
  80     the classname starts with "::", "DBIx::Class::Schema::Loader" is
  81     prepended. Defaults to "storage_type" in DBIx::Class::Schema (which must
  82     start with "::" when using DBIx::Class::Schema::Loader).
  83
  84     This is mostly useful for subclassing existing loaders or in conjunction
  85     with "dump_to_dir".
  86
  87   loader_options
  88     Argument: \%loader_options
  89
  90     Example in Synopsis above demonstrates a few common arguments. For
  91     detailed information on all of the arguments, most of which are only
  92     useful in fairly complex scenarios, see the
  93     DBIx::Class::Schema::Loader::Base documentation.
  94
  95     If you intend to use "loader_options", you must call "loader_options"
  96     before any connection is made, or embed the "loader_options" in the
  97     connection information itself as shown below. Setting "loader_options"
  98     after the connection has already been made is useless.
  99
 100   connection
 101     Arguments: @args
 102     Return Value: $new_schema
 103
 104     See "connection" in DBIx::Class::Schema for basic usage.
 105
 106     If the final argument is a hashref, and it contains the keys
 107     "loader_options" or "loader_class", those keys will be deleted, and
 108     their values value will be used for the loader options or class,
 109     respectively, just as if set via the "loader_options" or "loader_class"
 110     methods above.
 111
 112     The actual auto-loading operation (the heart of this module) will be
 113     invoked as soon as the connection information is defined.
 114
 115   clone
 116     See "clone" in DBIx::Class::Schema.
 117
 118   dump_to_dir
 119     Argument: $directory
 120
 121     Calling this as a class method on either DBIx::Class::Schema::Loader or
 122     any derived schema class will cause all schemas to dump manual versions
 123     of themselves to the named directory when they are loaded. In order to
 124     be effective, this must be set before defining a connection on this
 125     schema class or any derived object (as the loading happens as soon as
 126     both a connection and loader_options are set, and only once per class).
 127
 128     See "dump_directory" in DBIx::Class::Schema::Loader::Base for more
 129     details on the dumping mechanism.
 130
 131     This can also be set at module import time via the import option
 132     "dump_to_dir:/foo/bar" to DBIx::Class::Schema::Loader, where "/foo/bar"
 133     is the target directory.
 134
 135     Examples:
 136
 137         # My::Schema isa DBIx::Class::Schema::Loader, and has connection info
 138         #   hardcoded in the class itself:
 139         perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1
 140
 141         # Same, but no hard-coded connection, so we must provide one:
 142         perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)'
 143
 144         # Or as a class method, as long as you get it done *before* defining a
 145         #  connection on this schema class or any derived object:
 146         use My::Schema;
 147         My::Schema->dump_to_dir('/foo/bar');
 148         My::Schema->connection(........);
 149
 150         # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all
 151         #   derived schemas
 152         use My::Schema;
 153         use My::OtherSchema;
 154         DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar');
 155         My::Schema->connection(.......);
 156         My::OtherSchema->connection(.......);
 157
 158         # Another alternative to the above:
 159         use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |;
 160         use My::Schema;
 161         use My::OtherSchema;
 162         My::Schema->connection(.......);
 163         My::OtherSchema->connection(.......);
 164
 165   make_schema_at
 166     Arguments: $schema_class_name, \%loader_options, \@connect_info
 167     Return Value: $schema_class_name
 168
 169     This function creates a DBIx::Class schema from an existing RDBMS
 170     schema. With the "dump_directory" option, generates a set of DBIx::Class
 171     classes from an existing database schema read from the given dsn.
 172     Without a "dump_directory", creates schema classes in memory at runtime
 173     without generating on-disk class files.
 174
 175     For a complete list of supported loader_options, see
 176     DBIx::Class::Schema::Loader::Base
 177
 178     This function can be imported in the usual way, as illustrated in these
 179     Examples:
 180
 181         # Simple example, creates as a new class 'New::Schema::Name' in
 182         #  memory in the running perl interpreter.
 183         use DBIx::Class::Schema::Loader qw/ make_schema_at /;
 184         make_schema_at(
 185             'New::Schema::Name',
 186             { debug => 1 },
 187             [ 'dbi:Pg:dbname="foo"','postgres' ],
 188         );
 189
 190         # Inside a script, specifying a dump directory in which to write
 191         # class files
 192         use DBIx::Class::Schema::Loader qw/ make_schema_at /;
 193         make_schema_at(
 194             'New::Schema::Name',
 195             { debug => 1, dump_directory => './lib' },
 196             [ 'dbi:Pg:dbname="foo"','postgres' ],
 197         );
 198
 199   rescan
 200     Return Value: @new_monikers
 201
 202     Re-scans the database for newly added tables since the initial load, and
 203     adds them to the schema at runtime, including relationships, etc. Does
 204     not process drops or changes.
 205
 206     Returns a list of the new monikers added.
 207
 208 KNOWN ISSUES
 209   Multiple Database Schemas
 210     Currently the loader is limited to working within a single schema (using
 211     the underlying RDBMS's definition of "schema"). If you have a
 212     multi-schema database with inter-schema relationships (which is easy to
 213     do in PostgreSQL or DB2 for instance), you currently can only
 214     automatically load the tables of one schema, and relationships to tables
 215     in other schemas will be silently ignored.
 216
 217     At some point in the future, an intelligent way around this might be
 218     devised, probably by allowing the "db_schema" option to be an arrayref
 219     of schemas to load.
 220
 221     In "normal" DBIx::Class::Schema usage, manually-defined source classes
 222     and relationships have no problems crossing vendor schemas.
 223
 224 AUTHOR
 225     Brandon Black, "blblack@gmail.com"
 226
 227     Based on DBIx::Class::Loader by Sebastian Riedel
 228
 229     Based upon the work of IKEBE Tomohiro
 230
 231 THANK YOU
 232     Matt S Trout, all of the #dbix-class folks, and everyone who's ever sent
 233     in a bug report or suggestion.
 234
 235 LICENSE
 236     This library is free software; you can redistribute it and/or modify it
 237     under the same terms as Perl itself.
 238
 239 SEE ALSO
 240     DBIx::Class, DBIx::Class::Manual::ExampleSchema
 241