README

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