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         If you need to specify the DBIx::Class::Storage::DBI specific
 139         parameter "on_connect_do", or the related "sql_maker" options
 140         "limit_dialect", "quote_char", or "name_sep", you can place these
 141         options into a hashref as the final element of the "connect_info"
 142         arrayref. If in doubt, don't specify these options. You would know
 143         it if you needed them.
 144
 145         Examples:
 146
 147           connect_info => [ 'dbi:Pg:dbname=mypgdb', 'postgres', '' ],
 148
 149           connect_info => [
 150                             'dbi:SQLite:dbname=foo.db',
 151                             {
 152                               on_connect_do => [
 153                                 'PRAGMA synchronous = OFF',
 154                               ],
 155                             }
 156                           ],
 157
 158           connect_info => [
 159                             'dbi:Pg:dbname=mypgdb',
 160                             'postgres',
 161                             '',
 162                             { AutoCommit => 0 },
 163                             {
 164                               on_connect_do => [
 165                                 'some SQL statement',
 166                                 'another SQL statement',
 167                               ],
 168                             }
 169                           ],
 170
 171     storage_type
 172         Allows the use of a different "storage_type" than what is set in
 173         your "schema_class" (which in turn defaults to "::DBI" if not set in
 174         current DBIx::Class). Completely optional, and probably unnecessary
 175         for most people until other storage backends become available for
 176         DBIx::Class.
 177
 178 METHODS
 179     new Instantiates the Model based on the above-documented ->config
 180         parameters. The only required parameter is "schema_class".
 181         "connect_info" is required in the case that "schema_class" does not
 182         already have connection information defined for it.
 183
 184     schema
 185         Accessor which returns the connected schema being used by the this
 186         model. There are direct shortcuts on the model class itself for
 187         schema->resultset, schema->source, and schema->class.
 188
 189     composed_schema
 190         Accessor which returns the composed schema, which has no connection
 191         info, which was used in constructing the "schema" above. Useful for
 192         creating new connections based on the same schema/model. There are
 193         direct shortcuts from the model object for composed_schema->clone
 194         and composed_schema->connect
 195
 196     clone
 197         Shortcut for ->composed_schema->clone
 198
 199     connect
 200         Shortcut for ->composed_schema->connect
 201
 202     source
 203         Shortcut for ->schema->source
 204
 205     class
 206         Shortcut for ->schema->class
 207
 208     resultset
 209         Shortcut for ->schema->resultset
 210
 211     storage
 212         Provides an accessor for the connected schema's storage object. Used
 213         often for debugging and controlling transactions.
 214
 215 SEE ALSO
 216     General Catalyst Stuff:
 217
 218     Catalyst::Manual, Catalyst::Test, Catalyst::Request, Catalyst::Response,
 219     Catalyst::Helper, Catalyst,
 220
 221     Stuff related to DBIC and this Model style:
 222
 223     DBIx::Class, DBIx::Class::Schema, DBIx::Class::Schema::Loader,
 224     Catalyst::Helper::Model::DBIC::Schema
 225
 226 AUTHOR
 227     Brandon L Black, "blblack@gmail.com"
 228
 229 COPYRIGHT
 230     This program is free software, you can redistribute it and/or modify it
 231     under the same terms as Perl itself.
 232