Commit | Line | Data |
60557d3a |
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 | |