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