Catalyst::Model::DBIC::Schema(3pm)

1Catalyst::Model::DBIC::USscehremCao(n3t)ributed Perl DocCuamteanltyastti:o:nModel::DBIC::Schema(3)
2
3
4

NAME

6       Catalyst::Model::DBIC::Schema - DBIx::Class::Schema Model Class
7

SYNOPSIS

9       First, prepare your database schema using DBIx::Class, see
10       Catalyst::Helper::Model::DBIC::Schema for how to generate a
11       DBIx::Class::Schema from your database using the Helper script, and
12       DBIx::Class::Schema::Loader::Base.
13
14       A typical usage of the helper script would be:
15
16           script/myapp_create.pl model FilmDB DBIC::Schema MyApp::Schema::FilmDB \
17               create=static dbi:mysql:filmdb dbusername dbpass \
18               quote_char='`' name_sep='.'
19
20       If you are unfamiliar with DBIx::Class, see DBIx::Class::Manual::Intro
21       first.
22
23       These examples assume that you already have a schema called
24       "MyApp::Schema::FilmDB", which defines some Result classes for tables
25       in "MyApp::Schema::FilmDB::Result::Actor" and
26       "MyApp::Schema::FilmDB::Result::Film". Either created by the helper
27       script (as shown above) or manually.
28
29       The helper also creates a Model in "lib/MyApp/Model/FilmDB.pm", if you
30       already have a schema you can create just the Model using:
31
32           script/myapp_create.pl model FilmDB DBIC::Schema MyApp::Schema::FilmDB
33               dbi:mysql:filmdb dbusername dbpass
34
35       The connect_info is optional and will be hardcoded into the Model if
36       provided.  It's better to configure it in your Catalyst config file,
37       which will also override any hardcoded config, see "connect_info" for
38       examples.
39
40       Now you have a working Model which accesses your separate DBIC Schema.
41       This can be used/accessed in the normal Catalyst manner, via
42       "$c->model()":
43
44         my $db_model = $c->model('FilmDB');         # a Catalyst::Model
45         my $dbic     = $c->model('FilmDB')->schema; # the actual DBIC object
46
47       There is also a shortcut, which returns a DBIx::Class::ResultSet
48       directly, instead of a Catalyst::Model:
49
50         my $rs = $c->model('FilmDB::Actor');
51
52       See DBIx::Class::ResultSet to find out more about which methods can be
53       called on ResultSets.
54
55       You can also define your own ResultSet methods to encapsulate the
56       database/business logic of your applications. These go into, for
57       example, "lib/MyApp/Schema/FilmDB/ResultSet/Actor.pm". The class must
58       inherit from DBIx::Class::ResultSet and is automatically loaded.
59
60       Then call your methods like any other DBIx::Class::ResultSet method:
61
62           $c->model('FilmDB::Actor')->SAG_members
63
64   Some examples:
65         # to access schema methods directly:
66         $c->model('FilmDB')->schema->source(...);
67
68         # to access the source object, resultset, and class:
69         $c->model('FilmDB')->source(...);
70         $c->model('FilmDB')->resultset(...);
71         $c->model('FilmDB')->class(...);
72
73         # For resultsets, there's an even quicker shortcut:
74         $c->model('FilmDB::Actor')
75         # is the same as $c->model('FilmDB')->resultset('Actor')
76
77         # To get the composed schema for making new connections:
78         my $newconn = $c->model('FilmDB')->composed_schema->connect(...);
79
80         # Or the same thing via a convenience shortcut:
81         my $newconn = $c->model('FilmDB')->connect(...);
82
83         # or, if your schema works on different storage drivers:
84         my $newconn = $c->model('FilmDB')->composed_schema->clone();
85         $newconn->storage_type('::LDAP');
86         $newconn->connection(...);
87
88         # and again, a convenience shortcut
89         my $newconn = $c->model('FilmDB')->clone();
90         $newconn->storage_type('::LDAP');
91         $newconn->connection(...);
92
93       To set up authentication, see "Setting up DBIC authentication" below.
94

DESCRIPTION

96       This is a Catalyst Model for DBIx::Class::Schema-based Models.  See the
97       documentation for Catalyst::Helper::Model::DBIC::Schema for information
98       on generating these Models via Helper scripts.
99
100       When your Catalyst app starts up, a thin Model layer is created as an
101       interface to your DBIC Schema. It should be clearly noted that the
102       model object returned by "$c->model('FilmDB')" is NOT itself a DBIC
103       schema or resultset object, but merely a wrapper proving methods to
104       access the underlying schema.
105
106       In addition to this model class, a shortcut class is generated for each
107       source in the schema, allowing easy and direct access to a resultset of
108       the corresponding type. These generated classes are even thinner than
109       the model class, providing no public methods but simply hooking into
110       Catalyst's model() accessor via the ACCEPT_CONTEXT mechanism. The
111       complete contents of each generated class is roughly equivalent to the
112       following:
113
114         package MyApp::Model::FilmDB::Actor
115         sub ACCEPT_CONTEXT {
116             my ($self, $c) = @_;
117             $c->model('FilmDB')->resultset('Actor');
118         }
119
120       In short, there are three techniques available for obtaining a DBIC
121       resultset object:
122
123         # the long way
124         my $rs = $c->model('FilmDB')->schema->resultset('Actor');
125
126         # using the shortcut method on the model object
127         my $rs = $c->model('FilmDB')->resultset('Actor');
128
129         # using the generated class directly
130         my $rs = $c->model('FilmDB::Actor');
131
132       In order to add methods to a DBIC resultset, you cannot simply add them
133       to the source (row, table) definition class; you must define a separate
134       custom resultset class. This is just a matter of making a
135       "lib/MyApp/Schema/ResultSet/Actor.pm" class that inherits from
136       DBIx::Class::ResultSet, if you are using "load_namespaces" in
137       DBIx::Class::Schema, the default for helper script generated schemas.
138
139       See "Predefined searches" in DBIx::Class::Manual::Cookbook for
140       information on definining your own DBIx::Class::ResultSet classes for
141       use with "load_classes" in DBIx::Class::Schema, the old default.
142

CONFIG PARAMETERS

144   schema_class
145       This is the classname of your DBIx::Class::Schema Schema.  It needs to
146       be findable in @INC, but it does not need to be inside the
147       "Catalyst::Model::" namespace.  This parameter is required.
148
149   connect_info
150       This is an arrayref of connection parameters, which are specific to
151       your "storage_type" (see your storage type documentation for more
152       details).  If you only need one parameter (e.g. the DSN), you can just
153       pass a string instead of an arrayref.
154
155       This is not required if "schema_class" already has connection
156       information defined inside itself (which isn't highly recommended, but
157       can be done)
158
159       For DBIx::Class::Storage::DBI, which is the only supported
160       "storage_type" in DBIx::Class at the time of this writing, the
161       parameters are your dsn, username, password, and connect options
162       hashref.
163
164       See "connect_info" in DBIx::Class::Storage::DBI for a detailed
165       explanation of the arguments supported.
166
167       Examples:
168
169         connect_info => {
170           dsn => 'dbi:Pg:dbname=mypgdb',
171           user => 'postgres',
172           password => ''
173         }
174
175         connect_info => {
176           dsn => 'dbi:SQLite:dbname=foo.db',
177           on_connect_do => [
178             'PRAGMA synchronous = OFF',
179           ]
180         }
181
182         connect_info => {
183           dsn => 'dbi:Pg:dbname=mypgdb',
184           user => 'postgres',
185           password => '',
186           pg_enable_utf8 => 1,
187           on_connect_do => [
188             'some SQL statement',
189             'another SQL statement',
190           ],
191         }
192
193       Or using Config::General:
194
195           <Model::FilmDB>
196               schema_class   MyApp::Schema::FilmDB
197               traits Caching
198               <connect_info>
199                   dsn   dbi:Pg:dbname=mypgdb
200                   user   postgres
201                   password ""
202                   auto_savepoint 1
203                   quote_char """
204                   on_connect_do   some SQL statement
205                   on_connect_do   another SQL statement
206               </connect_info>
207               user_defined_schema_accessor foo
208           </Model::FilmDB>
209
210       or
211
212           <Model::FilmDB>
213               schema_class   MyApp::Schema::FilmDB
214               connect_info   dbi:SQLite:dbname=foo.db
215           </Model::FilmDB>
216
217       Or using YAML:
218
219         Model::MyDB:
220             schema_class: MyDB
221             traits: Caching
222             connect_info:
223                 dsn: dbi:Oracle:mydb
224                 user: mtfnpy
225                 password: mypass
226                 LongReadLen: 1000000
227                 LongTruncOk: 1
228                 on_connect_call: 'datetime_setup'
229                 quote_char: '"'
230
231       The old arrayref style with hashrefs for DBI then DBIx::Class options
232       is also supported:
233
234         connect_info => [
235           'dbi:Pg:dbname=mypgdb',
236           'postgres',
237           '',
238           {
239             pg_enable_utf8 => 1,
240           },
241           {
242             auto_savepoint => 1,
243             on_connect_do => [
244               'some SQL statement',
245               'another SQL statement',
246             ],
247           }
248         ]
249
250   traits
251       Array of Traits to apply to the instance. Traits are Moose::Roles.
252
253       They are relative to the "MyApp::TraitFor::Model::DBIC::Schema::", then
254       the "Catalyst::TraitFor::Model::DBIC::Schema::" namespaces, unless
255       prefixed with "+" in which case they are taken to be a fully qualified
256       name.  E.g.:
257
258           traits Caching
259           traits +MyApp::TraitFor::Model::Foo
260
261       A new instance is created at application time, so any consumed required
262       attributes, coercions and modifiers will work.
263
264       Traits are applied at "COMPONENT" in Catalyst::Component time using
265       CatalystX::Component::Traits.
266
267       "ref $self" will be an anon class if any traits are applied,
268       "$self->_original_class_name" will be the original class.
269
270       When writing a Trait, interesting points to modify are "BUILD", "setup"
271       and "ACCEPT_CONTEXT".
272
273       Traits that come with the distribution:
274
275       Catalyst::TraitFor::Model::DBIC::Schema::Caching
276       Catalyst::TraitFor::Model::DBIC::Schema::Replicated
277       Catalyst::TraitFor::Model::DBIC::Schema::SchemaProxy
278
279   storage_type
280       Allows the use of a different "storage_type" than what is set in your
281       "schema_class" (which in turn defaults to "::DBI" if not set in current
282       DBIx::Class).  Completely optional, and probably unnecessary for most
283       people until other storage backends become available for DBIx::Class.
284

ATTRIBUTES

286       The keys you pass in the model configuration are available as
287       attributes.
288
289       Other attributes available:
290
291   connect_info
292       Your connect_info args normalized to hashref form (with
293       dsn/user/password.) See "connect_info" in DBIx::Class::Storage::DBI for
294       more info on the hashref form of "connect_info".
295
296   model_name
297       The model name Catalyst uses to resolve this model, the part after
298       "::Model::" or "::M::" in your class name. E.g. if your class name is
299       "MyApp::Model::DB" the "model_name" will be "DB".
300
301   _default_cursor_class
302       What to reset your "cursor_class" in DBIx::Class::Storage::DBI to if a
303       custom one doesn't work out. Defaults to
304       DBIx::Class::Storage::DBI::Cursor.
305

ATTRIBUTES FROM MooseX::Traits::Pluggable

307   _original_class_name
308       The class name of your model before any "traits" are applied. E.g.
309       "MyApp::Model::DB".
310
311   _traits
312       Unresolved arrayref of traits passed in the config.
313
314   _resolved_traits
315       Traits you used resolved to full class names.
316

METHODS

318   new
319       Instantiates the Model based on the above-documented ->config
320       parameters.  The only required parameter is "schema_class".
321       "connect_info" is required in the case that "schema_class" does not
322       already have connection information defined for it.
323
324   schema
325       Accessor which returns the connected schema being used by the this
326       model.  There are direct shortcuts on the model class itself for
327       schema->resultset, schema->source, and schema->class.
328
329   composed_schema
330       Accessor which returns the composed schema, which has no connection
331       info, which was used in constructing the "schema" above.  Useful for
332       creating new connections based on the same schema/model.  There are
333       direct shortcuts from the model object for composed_schema->clone and
334       composed_schema->connect
335
336   clone
337       Shortcut for ->composed_schema->clone
338
339   connect
340       Shortcut for ->composed_schema->connect
341
342   source
343       Shortcut for ->schema->source
344
345   class
346       Shortcut for ->schema->class
347
348   resultset
349       Shortcut for ->schema->resultset
350
351   txn_do
352       Shortcut for ->schema->txn_do
353
354   txn_scope_guard
355       Shortcut for ->schema->txn_scope_guard
356
357   storage
358       Provides an accessor for the connected schema's storage object.  Used
359       often for debugging and controlling transactions.
360
361   setup
362       Called at "BUILD" time before configuration, but after "connect_info"
363       is set. To do something after configuuration use "after BUILD =>".
364
365       Receives a hashref of args passed to "BUILD".
366
367   ACCEPT_CONTEXT
368       Point of extension for doing things at "$c->model" time with context,
369       returns the model instance, see "ACCEPT_CONTEXT" in
370       Catalyst::Manual::Intro for more information.
371

ENVIRONMENT

373       CMDS_NO_SOURCES
374           Set this variable if you will be using schemas with no sources
375           (Result classes) to disable the warning. The warning is there
376           because having no Result classes is usually a mistake.
377

Setting up DBIC authentication

379       You can set this up with Catalyst::Authentication::Store::DBIx::Class
380       in MyApp.pm:
381
382         package MyApp;
383
384         use Catalyst qw/... Authentication .../;
385
386         ...
387
388         __PACKAGE__->config('Plugin::Authentication' =>
389                       {
390                           default_realm => 'members',
391                           members => {
392                               credential => {
393                                   class => 'Password',
394                                   password_field => 'password',
395                                   password_type => 'hashed'
396                                   password_hash_type => 'SHA-256'
397                               },
398                               store => {
399                                   class => 'DBIx::Class',
400                                   user_model => 'DB::User',
401                                   role_relation => 'roles',
402                                   role_field => 'rolename',
403                               }
404                           }
405                       });
406

METHOD PROXYING

408       The automatic proxying to the underlying DBIx::Class::Schema has been
409       removed as of version 0.34, to enable this feature add "SchemaProxy" to
410       "traits".
411
412       See Catalyst::TraitFor::Model::DBIC::Schema::SchemaProxy.
413

AUTHOR

434       Brandon L Black "blblack at gmail.com"
435

CONTRIBUTORS

437       caelum: Rafael Kitover "rkitover at cpan.org"
438
439       dandv: Dan Dascalescu "dandv at cpan.org"
440
441       bluefeet: Aran Deltac "bluefeet@cpan.org"
442
443       t0m: Tomas Doran "bobtfish@bobtfish.net"
444
445       osfameron: "osfameron@cpan.org"
446
447       ozum: Ozum Eldogan "ozum@ozum.net"
448
449       Pavel I. Shaydo "zwon@trinitum.org"
450

COPYRIGHT

452       Copyright (c) 2006 - 2009 the Catalyst::Model::DBIC::Schema "AUTHOR"
453       and "CONTRIBUTORS" as listed above.
454

LICENSE

456       This program is free software. You can redistribute it and/or modify it
457       under the same terms as Perl itself.
458
459
460
461perl v5.12.0                      2010-02-04  Catalyst::Model::DBIC::Schema(3)