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_names=1
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 a hashref or arrayref of connection parameters, which are
151       specific to your "storage_type" (see your storage type documentation
152       for more details). If you only need one parameter (e.g. the DSN), you
153       can just pass a string.
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_names 1
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_names: 1
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       Catalyst::TraitFor::Model::DBIC::Schema::PerRequestSchema
279
280   compose_namespaces
281       This model calls "compose_namespace" in DBIx::Class::Schema by default
282       to install classes into the model namespaces. You can turn that off by
283       setting this attribute to false. Default is true.
284
285   install_model_shortcuts
286       If you don't want shortcut models so you can do e.g.
287       "$c->model('DB::Book')" set this attribute to false, Default is true.
288
289   storage_type
290       Allows the use of a different "storage_type" than what is set in your
291       "schema_class" (which in turn defaults to "::DBI" if not set in current
292       DBIx::Class).  Completely optional, and probably unnecessary for most
293       people until other storage backends become available for DBIx::Class.
294

ATTRIBUTES

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

ATTRIBUTES FROM MooseX::Traits::Pluggable

317   _original_class_name
318       The class name of your model before any "traits" are applied. E.g.
319       "MyApp::Model::DB".
320
321   _traits
322       Unresolved arrayref of traits passed in the config.
323
324   _resolved_traits
325       Traits you used resolved to full class names.
326

CONFIGURING YOUR SCHEMA AND RESULTSETS

328       See the documentation for
329       Catalyst::TraitFor::Model::DBIC::Schema::SchemaProxy for instructions
330       on how to pass config values from your Catalyst config to your
331       DBIx::Class::Schema and/or DBIx::Class::ResultSet classes.
332

METHODS

334   new
335       Instantiates the Model based on the above-documented ->config
336       parameters.  The only required parameter is "schema_class".
337       "connect_info" is required in the case that "schema_class" does not
338       already have connection information defined for it.
339
340   schema
341       Accessor which returns the connected schema being used by the this
342       model.  There are direct shortcuts on the model class itself for
343       schema->resultset, schema->source, and schema->class.
344
345   composed_schema
346       Accessor which returns the composed schema, which has no connection
347       info, which was used in constructing the "schema". Useful for creating
348       new connections based on the same schema/model.  There are direct
349       shortcuts from the model object for composed_schema->clone and
350       composed_schema->connect
351
352       If "compose_namespaces" is not true, "composed_schema" is equivalent to
353       "$model->schema_class->clone".
354
355   clone
356       Shortcut for ->composed_schema->clone
357
358   connect
359       Shortcut for ->composed_schema->connect
360
361   source
362       Shortcut for ->schema->source
363
364   class
365       Shortcut for ->schema->class
366
367   resultset
368       Shortcut for ->schema->resultset
369
370   txn_do
371       Shortcut for ->schema->txn_do
372
373   txn_scope_guard
374       Shortcut for ->schema->txn_scope_guard
375
376   storage
377       Provides an accessor for the connected schema's storage object.
378
379       See DBIx::Class::Storage and DBIx::Class::Storage::DBI.
380
381   setup
382       Called at "BUILD" time before configuration, but after "connect_info"
383       is set. To do something after configuuration use "after BUILD =>".
384
385       Receives a hashref of args passed to "BUILD".
386
387   ACCEPT_CONTEXT
388       Point of extension for doing things at "$c->model" time with context,
389       returns the model instance, see "ACCEPT_CONTEXT" in
390       Catalyst::Manual::Intro for more information.
391

ENVIRONMENT

393       CMDS_NO_SOURCES
394           Set this variable if you will be using schemas with no sources
395           (Result classes) to disable the warning. The warning is there
396           because having no Result classes is usually a mistake.
397

Setting up DBIC authentication

399       You can set this up with Catalyst::Authentication::Store::DBIx::Class
400       in MyApp.pm:
401
402         package MyApp;
403
404         use Catalyst qw/... Authentication .../;
405
406         ...
407
408         __PACKAGE__->config('Plugin::Authentication' =>
409                       {
410                           default_realm => 'members',
411                           members => {
412                               credential => {
413                                   class => 'Password',
414                                   password_field => 'password',
415                                   password_type => 'hashed'
416                                   password_hash_type => 'SHA-256'
417                               },
418                               store => {
419                                   class => 'DBIx::Class',
420                                   user_model => 'DB::User',
421                                   role_relation => 'roles',
422                                   role_field => 'rolename',
423                               }
424                           }
425                       });
426

METHOD PROXYING

428       The automatic proxying to the underlying DBIx::Class::Schema has been
429       removed as of version 0.34, to enable this feature add "SchemaProxy" to
430       "traits".
431
432       See Catalyst::TraitFor::Model::DBIC::Schema::SchemaProxy.
433

AUTHOR

455       Brandon L Black "blblack at gmail.com"
456

CONTRIBUTORS

458       caelum: Rafael Kitover "rkitover at cpan.org"
459
460       dandv: Dan Dascalescu "dandv at cpan.org"
461
462       bluefeet: Aran Deltac "bluefeet@cpan.org"
463
464       t0m: Tomas Doran "bobtfish@bobtfish.net"
465
466       osfameron: "osfameron@cpan.org"
467
468       ozum: Ozum Eldogan "ozum@ozum.net"
469
470       Pavel I. Shaydo "zwon@trinitum.org"
471
472       SineSwiper: Brendan Byrd <byrd.b@insightcom.com>
473

COPYRIGHT

475       Copyright (c) 2006 - 2010 the Catalyst::Model::DBIC::Schema "AUTHOR"
476       and "CONTRIBUTORS" as listed above.
477

LICENSE

479       This program is free software. You can redistribute it and/or modify it
480       under the same terms as Perl itself.
481
482
483
484perl v5.38.0                      2023-07-31  Catalyst::Model::DBIC::Schema(3)