X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README;h=6f7206df6a19494ebc4da86a30f39c4bf07b500f;hb=018eb0e2f55391533246baeb6a176e6aa694f7a1;hp=e35d435d4e9771ff0bab95a47c6d4d0c4fe5112c;hpb=3d8cdccc63d51e14e77b37ed96cd49e091d5d7c5;p=catagits%2FCatalyst-Model-DBIC-Schema.git diff --git a/README b/README index e35d435..6f7206d 100644 --- a/README +++ b/README @@ -2,74 +2,167 @@ NAME Catalyst::Model::DBIC::Schema - DBIx::Class::Schema Model Class SYNOPSIS - package MyApp::Model::Foo; - use strict; - use base 'Catalyst::Model::DBIC::Schema'; + Manual creation of a DBIx::Class::Schema and a + Catalyst::Model::DBIC::Schema: - __PACKAGE__->config( - schema_class => 'Foo::SchemaClass', - connect_info => [ 'dbi:Pg:dbname=foodb', - 'postgres', - '', - { AutoCommit => 1 }, - ], - ); + 1. Create the DBIx:Class schema in MyApp/Schema/FilmDB.pm: - 1; + package MyApp::Schema::FilmDB; + use base qw/DBIx::Class::Schema/; - # In controller code: + __PACKAGE__->load_classes(qw/Actor Role/); - # ->schema To access schema methods: - $c->model('Foo')->schema->source(...); + 2. Create some classes for the tables in the database, for example an + Actor in MyApp/Schema/FilmDB/Actor.pm: - # certain ->schema methods (source, resultset, class) have shortcuts - $c->model('Foo')->source(...); - $c->model('Foo')->resultset(...); - $c->model('Foo')->class(...); + package MyApp::Schema::FilmDB::Actor; + use base qw/DBIx::Class/ - # For resultsets, there's an even quicker shortcut: - $c->model('Foo::Bar') - # is the same as $c->model('Foo')->resultset('Bar') + __PACKAGE__->load_components(qw/Core/); + __PACKAGE__->table('actor'); - # To get the composed schema for making new connections: - my $newconn = $c->model('Foo')->composed_schema->connect(...); + ... - # Or the same thing via a convenience shortcut: - my $newconn = $c->model('Foo')->connect(...); + and a Role in MyApp/Schema/Role.pm: - # or, if your schema works on different storage drivers: - my $newconn = $c->model('Foo')->composed_schema->clone(); - $newconn->storage_type('::LDAP'); - $newconn->connection(...); + package MyApp::Schema::FilmDB::Role; + use base qw/DBIx::Class/ - # and again, a convenience shortcut - my $newconn = $c->model('Foo')->clone(); - $newconn->storage_type('::LDAP'); - $newconn->connection(...); + __PACKAGE__->load_components(qw/Core/); + __PACKAGE__->table('role'); + + ... + + Notice that the schema is in MyApp::Schema, not in MyApp::Model. + This way it's usable as a standalone module and you can test/run it + without Catalyst. + + 3. To expose it to Catalyst as a model, you should create a DBIC Model + in MyApp/Model/FilmDB.pm: + + package MyApp::Model::FilmDB; + use base qw/Catalyst::Model::DBIC::Schema/; + + __PACKAGE__->config( + schema_class => 'MyApp::Schema::FilmDB', + connect_info => [ + "DBI:...", + "username", + "password", + {AutoCommit => 1} + ] + ); + + See below for a full list of the possible config parameters. + + Now you have a working Model, accessing your separate DBIC Schema. Which + can be used/accessed in the normal Catalyst manner, via $c->model(): + + my $actor = $c->model('FilmDB::Actor')->find(1); + + You can also use it to set up DBIC authentication with + Authentication::Store::DBIC in MyApp.pm: + + package MyApp; + + use Catalyst qw/... Authentication::Store::DBIC/; + + ... + + __PACKAGE__->config->{authentication}{dbic} = { + user_class => 'FilmDB::Actor', + user_field => 'name', + password_field => 'password' + } + + "$c->model()" returns a DBIx::Class::ResultSet for the source name + parameter passed. To find out more about which methods can be called on + a ResultSet, or how to add your own methods to it, please see the + ResultSet documentation in the DBIx::Class distribution. + + Some examples are given below: + + # to access schema methods directly: + $c->model('FilmDB')->schema->source(...); + + # to access the source object, resultset, and class: + $c->model('FilmDB')->source(...); + $c->model('FilmDB')->resultset(...); + $c->model('FilmDB')->class(...); + + # For resultsets, there's an even quicker shortcut: + $c->model('FilmDB::Actor') + # is the same as $c->model('FilmDB')->resultset('Actor') + + # To get the composed schema for making new connections: + my $newconn = $c->model('FilmDB')->composed_schema->connect(...); + + # Or the same thing via a convenience shortcut: + my $newconn = $c->model('FilmDB')->connect(...); + + # or, if your schema works on different storage drivers: + my $newconn = $c->model('FilmDB')->composed_schema->clone(); + $newconn->storage_type('::LDAP'); + $newconn->connection(...); + + # and again, a convenience shortcut + my $newconn = $c->model('FilmDB')->clone(); + $newconn->storage_type('::LDAP'); + $newconn->connection(...); DESCRIPTION This is a Catalyst Model for DBIx::Class::Schema-based Models. See the - documentation for Catalyst::Helper::Model::DBIC::Schema and - Catalyst::Helper::Model::DBIC::SchemaLoader for information on - generating these Models via Helper scripts. The latter of the two will - also generated a DBIx::Class::Schema::Loader-based Schema class for you. + documentation for Catalyst::Helper::Model::DBIC::Schema for information + on generating these Models via Helper scripts. CONFIG PARAMETERS schema_class This is the classname of your DBIx::Class::Schema Schema. It needs - to be findable in @INC, but it does not need to be underneath - "Catalyst::Model::". This parameter is required. + to be findable in @INC, but it does not need to be inside the + "Catalyst::Model::" namespace. This parameter is required. connect_info This is an arrayref of connection parameters, which are specific to - your "storage_type". For "::DBI", which is the only supported - "storage_type" in DBIx::Class at the time of this writing, the 4 + your "storage_type" (see your storage type documentation for more + details). + + This is not required if "schema_class" already has connection + information defined inside itself (which isn't highly recommended, + but can be done) + + For DBIx::Class::Storage::DBI, which is the only supported + "storage_type" in DBIx::Class at the time of this writing, the parameters are your dsn, username, password, and connect options hashref. - This is not required if "schema_class" already has connection - information defined in itself (which would be the case for a Schema - defined by DBIx::Class::Schema::Loader, for instance). + See "connect_info" in DBIx::Class::Storage::DBI for a detailed + explanation of the arguments supported. + + Examples: + + connect_info => [ 'dbi:Pg:dbname=mypgdb', 'postgres', '' ], + + connect_info => [ + 'dbi:SQLite:dbname=foo.db', + { + on_connect_do => [ + 'PRAGMA synchronous = OFF', + ], + } + ], + + connect_info => [ + 'dbi:Pg:dbname=mypgdb', + 'postgres', + '', + { AutoCommit => 0 }, + { + on_connect_do => [ + 'some SQL statement', + 'another SQL statement', + ], + } + ], storage_type Allows the use of a different "storage_type" than what is set in @@ -86,8 +179,8 @@ METHODS schema Accessor which returns the connected schema being used by the this - model. There are already direct shortcuts on the model class itself - for schema->resultset, schema->source, and schema->class. + model. There are direct shortcuts on the model class itself for + schema->resultset, schema->source, and schema->class. composed_schema Accessor which returns the composed schema, which has no connection @@ -124,8 +217,7 @@ SEE ALSO Stuff related to DBIC and this Model style: DBIx::Class, DBIx::Class::Schema, DBIx::Class::Schema::Loader, - Catalyst::Helper::Model::DBIC::Schema, - Catalyst::Helper::Model::DBIC::SchemaLoader + Catalyst::Helper::Model::DBIC::Schema AUTHOR Brandon L Black, "blblack@gmail.com"