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     Argument: $loader_class
  53
  54     Set the loader class to be instantiated when "connection" is called. If
  55     the classname starts with "::", "DBIx::Class::Schema::Loader" is
  56     prepended. Defaults to "storage_type" in DBIx::Class::Schema (which must
  57     start with "::" when using DBIx::Class::Schema::Loader).
  58
  59     This is mostly useful for subclassing existing loaders or in conjunction
  60     with "dump_to_dir".
  61
  62   loader_options
  63     Argument: \%loader_options
  64
  65     Example in Synopsis above demonstrates a few common arguments. For
  66     detailed information on all of the arguments, most of which are only
  67     useful in fairly complex scenarios, see the
  68     DBIx::Class::Schema::Loader::Base documentation.
  69
  70     If you intend to use "loader_options", you must call "loader_options"
  71     before any connection is made, or embed the "loader_options" in the
  72     connection information itself as shown below. Setting "loader_options"
  73     after the connection has already been made is useless.
  74
  75   connection
  76     Arguments: @args
  77     Return Value: $new_schema
  78
  79     See "connection" in DBIx::Class::Schema for basic usage.
  80
  81     If the final argument is a hashref, and it contains the keys
  82     "loader_options" or "loader_class", those keys will be deleted, and
  83     their values value will be used for the loader options or class,
  84     respectively, just as if set via the "loader_options" or "loader_class"
  85     methods above.
  86
  87     The actual auto-loading operation (the heart of this module) will be
  88     invoked as soon as the connection information is defined.
  89
  90   clone
  91     See "clone" in DBIx::Class::Schema.
  92
  93   dump_to_dir
  94     Argument: $directory
  95
  96     Calling this as a class method on either DBIx::Class::Schema::Loader or
  97     any derived schema class will cause all affected schemas to dump manual
  98     versions of themselves to the named directory when they are loaded. In
  99     order to be effective, this must be set before defining a connection on
 100     this schema class or any derived object (as the loading happens as soon
 101     as both a connection and loader_options are set, and only once per
 102     class).
 103
 104     See "dump_directory" in DBIx::Class::Schema::Loader::Base for more
 105     details on the dumping mechanism.
 106
 107     This can also be set at module import time via the import option
 108     "dump_to_dir:/foo/bar" to DBIx::Class::Schema::Loader, where "/foo/bar"
 109     is the target directory.
 110
 111     Examples:
 112
 113         # My::Schema isa DBIx::Class::Schema::Loader, and has connection info
 114         #   hardcoded in the class itself:
 115         perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e1
 116
 117         # Same, but no hard-coded connection, so we must provide one:
 118         perl -MDBIx::Class::Schema::Loader=dump_to_dir:/foo/bar -MMy::Schema -e 'My::Schema->connection("dbi:Pg:dbname=foo", ...)'
 119
 120         # Or as a class method, as long as you get it done *before* defining a
 121         #  connection on this schema class or any derived object:
 122         use My::Schema;
 123         My::Schema->dump_to_dir('/foo/bar');
 124         My::Schema->connection(........);
 125
 126         # Or as a class method on the DBIx::Class::Schema::Loader itself, which affects all
 127         #   derived schemas
 128         use My::Schema;
 129         use My::OtherSchema;
 130         DBIx::Class::Schema::Loader->dump_to_dir('/foo/bar');
 131         My::Schema->connection(.......);
 132         My::OtherSchema->connection(.......);
 133
 134         # Another alternative to the above:
 135         use DBIx::Class::Schema::Loader qw| dump_to_dir:/foo/bar |;
 136         use My::Schema;
 137         use My::OtherSchema;
 138         My::Schema->connection(.......);
 139         My::OtherSchema->connection(.......);
 140
 141   make_schema_at
 142     Arguments: $schema_name, \%loader_options, \@connect_info
 143     Return Value: $schema_name
 144
 145     This simple function allows one to create a Loader-based schema
 146     in-memory on the fly without any on-disk class files of any kind. When
 147     used with the "dump_directory" option, you can use this to generate a
 148     rough draft manual schema from a dsn without the intermediate step of
 149     creating a physical Loader-based schema class.
 150
 151     The return value is the input class name.
 152
 153     This function can be exported/imported by the normal means, as
 154     illustrated in these Examples:
 155
 156         # Simple example, creates as a new class 'New::Schema::Name' in
 157         #  memory in the running perl interpreter.
 158         use DBIx::Class::Schema::Loader qw/ make_schema_at /;
 159         make_schema_at(
 160             'New::Schema::Name',
 161             { debug => 1 },
 162             [ 'dbi:Pg:dbname="foo"','postgres' ],
 163         );
 164
 165         # Complex: dump loaded schema to disk, all from the commandline:
 166         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" ])'
 167
 168         # Same, but inside a script, and using a different way to specify the
 169         # dump directory:
 170         use DBIx::Class::Schema::Loader qw/ make_schema_at /;
 171         make_schema_at(
 172             'New::Schema::Name',
 173             { debug => 1, dump_directory => './lib' },
 174             [ 'dbi:Pg:dbname="foo"','postgres' ],
 175         );
 176
 177   rescan
 178     Return Value: @new_monikers
 179
 180     Re-scans the database for newly added tables since the initial load, and
 181     adds them to the schema at runtime, including relationships, etc. Does
 182     not process drops or changes.
 183
 184     Returns a list of the new monikers added.
 185
 186 EXAMPLE
 187     Using the example in DBIx::Class::Manual::ExampleSchema as a basis
 188     replace the DB::Main with the following code:
 189
 190       package DB::Main;
 191
 192       use base qw/DBIx::Class::Schema::Loader/;
 193
 194       __PACKAGE__->loader_options(
 195           debug         => 1,
 196       );
 197       __PACKAGE__->connection('dbi:SQLite:example.db');
 198
 199       1;
 200
 201     and remove the Main directory tree (optional). Every thing else should
 202     work the same
 203
 204 KNOWN ISSUES
 205   Multiple Database Schemas
 206     Currently the loader is limited to working within a single schema (using
 207     the database vendors' definition of "schema"). If you have a
 208     multi-schema database with inter-schema relationships (which is easy to
 209     do in PostgreSQL or DB2 for instance), you only get to automatically
 210     load the tables of one schema, and any relationships to tables in other
 211     schemas will be silently ignored.
 212
 213     At some point in the future, an intelligent way around this might be
 214     devised, probably by allowing the "db_schema" option to be an arrayref
 215     of schemas to load.
 216
 217     In "normal" DBIx::Class::Schema usage, manually-defined source classes
 218     and relationships have no problems crossing vendor schemas.
 219
 220 AUTHOR
 221     Brandon Black, "blblack@gmail.com"
 222
 223     Based on DBIx::Class::Loader by Sebastian Riedel
 224
 225     Based upon the work of IKEBE Tomohiro
 226
 227 THANK YOU
 228     Matt S Trout, all of the #dbix-class folks, and everyone who's ever sent
 229     in a bug report or suggestion.
 230
 231 LICENSE
 232     This library is free software; you can redistribute it and/or modify it
 233     under the same terms as Perl itself.
 234
 235 SEE ALSO
 236     DBIx::Class, DBIx::Class::Manual::ExampleSchema
 237