README

   1 NAME
   2     Catalyst::Model::DBIC::Schema - DBIx::Class::Schema Model Class
   3
   4 SYNOPSIS
   5     Manual creation of a DBIx::Class::Schema and a
   6     Catalyst::Model::DBIC::Schema:
   7
   8     1.  Create the DBIx:Class schema in MyApp/Schema/FilmDB.pm:
   9
  10           package MyApp::Schema::FilmDB;
  11           use base qw/DBIx::Class::Schema/;
  12
  13           __PACKAGE__->load_classes(qw/Actor Role/);
  14
  15     2.  Create some classes for the tables in the database, for example an
  16         Actor in MyApp/Schema/FilmDB/Actor.pm:
  17
  18           package MyApp::Schema::FilmDB::Actor;
  19           use base qw/DBIx::Class/
  20
  21           __PACKAGE__->load_components(qw/Core/);
  22           __PACKAGE__->table('actor');
  23
  24           ...
  25
  26         and a Role in MyApp/Schema/Role.pm:
  27
  28           package MyApp::Schema::FilmDB::Role;
  29           use base qw/DBIx::Class/
  30
  31           __PACKAGE__->load_components(qw/Core/);
  32           __PACKAGE__->table('role');
  33
  34           ...
  35
  36         Notice that the schema is in MyApp::Schema, not in MyApp::Model.
  37         This way it's usable as a standalone module and you can test/run it
  38         without Catalyst.
  39
  40     3.  To expose it to Catalyst as a model, you should create a DBIC Model
  41         in MyApp/Model/FilmDB.pm:
  42
  43           package MyApp::Model::FilmDB;
  44           use base qw/Catalyst::Model::DBIC::Schema/;
  45
  46           __PACKAGE__->config(
  47               schema_class => 'MyApp::Schema::FilmDB',
  48               connect_info => [
  49                                 "DBI:...",
  50                                 "username",
  51                                 "password",
  52                                 {AutoCommit => 1}
  53                               ]
  54           );
  55
  56         See below for a full list of the possible config parameters.
  57
  58     Now you have a working Model, accessing your separate DBIC Schema. Which
  59     can be used/accessed in the normal Catalyst manner, via $c->model():
  60
  61       my $actor = $c->model('FilmDB::Actor')->find(1);
  62
  63     You can also use it to set up DBIC authentication with
  64     Authentication::Store::DBIC in MyApp.pm:
  65
  66       package MyApp;
  67
  68       use Catalyst qw/... Authentication::Store::DBIC/;
  69
  70       ...
  71
  72       __PACKAGE__->config->{authentication}{dbic} = {
  73           user_class      => 'FilmDB::Actor',
  74           user_field      => 'name',
  75           password_field  => 'password'
  76       }
  77
  78     "$c->model()" returns a DBIx::Class::ResultSet for the source name
  79     parameter passed. To find out more about which methods can be called on
  80     a ResultSet, or how to add your own methods to it, please see the
  81     ResultSet documentation in the DBIx::Class distribution.
  82
  83     Some examples are given below:
  84
  85       # to access schema methods directly:
  86       $c->model('FilmDB')->schema->source(...);
  87
  88       # to access the source object, resultset, and class:
  89       $c->model('FilmDB')->source(...);
  90       $c->model('FilmDB')->resultset(...);
  91       $c->model('FilmDB')->class(...);
  92
  93       # For resultsets, there's an even quicker shortcut:
  94       $c->model('FilmDB::Actor')
  95       # is the same as $c->model('FilmDB')->resultset('Actor')
  96
  97       # To get the composed schema for making new connections:
  98       my $newconn = $c->model('FilmDB')->composed_schema->connect(...);
  99
 100       # Or the same thing via a convenience shortcut:
 101       my $newconn = $c->model('FilmDB')->connect(...);
 102
 103       # or, if your schema works on different storage drivers:
 104       my $newconn = $c->model('FilmDB')->composed_schema->clone();
 105       $newconn->storage_type('::LDAP');
 106       $newconn->connection(...);
 107
 108       # and again, a convenience shortcut
 109       my $newconn = $c->model('FilmDB')->clone();
 110       $newconn->storage_type('::LDAP');
 111       $newconn->connection(...);
 112
 113 DESCRIPTION
 114     This is a Catalyst Model for DBIx::Class::Schema-based Models. See the
 115     documentation for Catalyst::Helper::Model::DBIC::Schema for information
 116     on generating these Models via Helper scripts.
 117
 118 CONFIG PARAMETERS
 119     schema_class
 120         This is the classname of your DBIx::Class::Schema Schema. It needs
 121         to be findable in @INC, but it does not need to be inside the
 122         "Catalyst::Model::" namespace. This parameter is required.
 123
 124     connect_info
 125         This is an arrayref of connection parameters, which are specific to
 126         your "storage_type" (see your storage type documentation for more
 127         details).
 128
 129         This is not required if "schema_class" already has connection
 130         information defined inside itself (which isn't highly recommended,
 131         but can be done)
 132
 133         For DBIx::Class::Storage::DBI, which is the only supported
 134         "storage_type" in DBIx::Class at the time of this writing, the
 135         parameters are your dsn, username, password, and connect options
 136         hashref.
 137
 138         See "connect_info" in DBIx::Class::Storage::DBI for a detailed
 139         explanation of the arguments supported.
 140
 141         Examples:
 142
 143           connect_info => [ 'dbi:Pg:dbname=mypgdb', 'postgres', '' ],
 144
 145           connect_info => [
 146                             'dbi:SQLite:dbname=foo.db',
 147                             {
 148                               on_connect_do => [
 149                                 'PRAGMA synchronous = OFF',
 150                               ],
 151                             }
 152                           ],
 153
 154           connect_info => [
 155                             'dbi:Pg:dbname=mypgdb',
 156                             'postgres',
 157                             '',
 158                             { AutoCommit => 0 },
 159                             {
 160                               on_connect_do => [
 161                                 'some SQL statement',
 162                                 'another SQL statement',
 163                               ],
 164                             }
 165                           ],
 166
 167     storage_type
 168         Allows the use of a different "storage_type" than what is set in
 169         your "schema_class" (which in turn defaults to "::DBI" if not set in
 170         current DBIx::Class). Completely optional, and probably unnecessary
 171         for most people until other storage backends become available for
 172         DBIx::Class.
 173
 174 METHODS
 175     new Instantiates the Model based on the above-documented ->config
 176         parameters. The only required parameter is "schema_class".
 177         "connect_info" is required in the case that "schema_class" does not
 178         already have connection information defined for it.
 179
 180     schema
 181         Accessor which returns the connected schema being used by the this
 182         model. There are direct shortcuts on the model class itself for
 183         schema->resultset, schema->source, and schema->class.
 184
 185     composed_schema
 186         Accessor which returns the composed schema, which has no connection
 187         info, which was used in constructing the "schema" above. Useful for
 188         creating new connections based on the same schema/model. There are
 189         direct shortcuts from the model object for composed_schema->clone
 190         and composed_schema->connect
 191
 192     clone
 193         Shortcut for ->composed_schema->clone
 194
 195     connect
 196         Shortcut for ->composed_schema->connect
 197
 198     source
 199         Shortcut for ->schema->source
 200
 201     class
 202         Shortcut for ->schema->class
 203
 204     resultset
 205         Shortcut for ->schema->resultset
 206
 207     storage
 208         Provides an accessor for the connected schema's storage object. Used
 209         often for debugging and controlling transactions.
 210
 211 SEE ALSO
 212     General Catalyst Stuff:
 213
 214     Catalyst::Manual, Catalyst::Test, Catalyst::Request, Catalyst::Response,
 215     Catalyst::Helper, Catalyst,
 216
 217     Stuff related to DBIC and this Model style:
 218
 219     DBIx::Class, DBIx::Class::Schema, DBIx::Class::Schema::Loader,
 220     Catalyst::Helper::Model::DBIC::Schema
 221
 222 AUTHOR
 223     Brandon L Black, "blblack@gmail.com"
 224
 225 COPYRIGHT
 226     This program is free software, you can redistribute it and/or modify it
 227     under the same terms as Perl itself.
 228