Commit | Line | Data |
b8e1e21f |
1 | package DBIx::Class::Relationship; |
2 | |
3 | use strict; |
4 | use warnings; |
5 | |
1edd1722 |
6 | use base qw/DBIx::Class/; |
55e2d745 |
7 | |
07037f89 |
8 | __PACKAGE__->load_own_components(qw/ |
7411204b |
9 | Helpers |
07037f89 |
10 | Accessor |
11 | CascadeActions |
12 | ProxyMethods |
13 | Base |
14 | /); |
b8e1e21f |
15 | |
75d07914 |
16 | =head1 NAME |
34d52be2 |
17 | |
18 | DBIx::Class::Relationship - Inter-table relationships |
19 | |
20 | =head1 SYNOPSIS |
21 | |
75d07914 |
22 | MyDB::Schema::Actor->has_many('actorroles' => 'MyDB::Schema::ActorRole', |
d2113a68 |
23 | 'actor'); |
75d07914 |
24 | MyDB::Schema::Role->has_many('actorroles' => 'MyDB::Schema::ActorRole', |
d2113a68 |
25 | 'role'); |
26 | MyDB::Schema::ActorRole->belongs_to('role' => 'MyDB::Schema::Role'); |
27 | MyDB::Schema::ActorRole->belongs_to('actor' => 'MyDB::Schema::Actor'); |
28 | |
29 | MyDB::Schema::Role->many_to_many('actors' => 'actorroles', 'actor'); |
30 | MyDB::Schema::Actor->many_to_many('roles' => 'actorroles', 'role'); |
31 | |
32 | $schema->resultset('Actor')->roles(); |
33 | $schema->resultset('Role')->search_related('actors', { Name => 'Fred' }); |
fca27358 |
34 | $schema->resultset('ActorRole')->add_to_roles({ Name => 'Sherlock Holmes'}); |
d2113a68 |
35 | |
36 | See L<DBIx::Class::Manual::Cookbook> for more. |
37 | |
34d52be2 |
38 | =head1 DESCRIPTION |
39 | |
bc1171c3 |
40 | This class provides methods to set up relationships between the tables |
41 | in your database model. Relationships are the most useful and powerful |
42 | technique that L<DBIx::Class> provides. To create efficient database queries, |
43 | create relationships between any and all tables that have something in |
44 | common, for example if you have a table Authors: |
45 | |
46 | ID | Name | Age |
47 | ------------------ |
48 | 1 | Fred | 30 |
49 | 2 | Joe | 32 |
50 | |
51 | and a table Books: |
52 | |
53 | ID | Author | Name |
54 | -------------------- |
55 | 1 | 1 | Rulers of the universe |
56 | 2 | 1 | Rulers of the galaxy |
57 | |
58 | Then without relationships, the method of getting all books by Fred goes like |
59 | this: |
60 | |
61 | my $fred = $schema->resultset('Author')->find({ Name => 'Fred' }); |
62 | my $fredsbooks = $schema->resultset('Book')->search({ Author => $fred->ID }); |
2f0790c4 |
63 | |
bc1171c3 |
64 | With a has_many relationship called "books" on Author (see below for details), |
65 | we can do this instead: |
66 | |
67 | my $fredsbooks = $schema->resultset('Author')->find({ Name => 'Fred' })->books; |
68 | |
75d07914 |
69 | Each relationship sets up an accessor method on the |
bc1171c3 |
70 | L<DBIx::Class::Manual::Glossary/"Row"> objects that represent the items |
71 | of your table. From L<DBIx::Class::Manual::Glossary/"ResultSet"> objects, |
75d07914 |
72 | the relationships can be searched using the "search_related" method. |
bc1171c3 |
73 | In list context, each returns a list of Row objects for the related class, |
74 | in scalar context, a new ResultSet representing the joined tables is |
75 | returned. Thus, the calls can be chained to produce complex queries. |
76 | Since the database is not actually queried until you attempt to retrieve |
77 | the data for an actual item, no time is wasted producing them. |
78 | |
bc0c9800 |
79 | my $cheapfredbooks = $schema->resultset('Author')->find({ |
80 | Name => 'Fred', |
81 | })->books->search_related('prices', { |
82 | Price => { '<=' => '5.00' }, |
83 | }); |
bc1171c3 |
84 | |
85 | will produce a query something like: |
86 | |
75d07914 |
87 | SELECT * FROM Author me |
bc1171c3 |
88 | LEFT JOIN Books books ON books.author = me.id |
89 | LEFT JOIN Prices prices ON prices.book = books.id |
90 | WHERE prices.Price <= 5.00 |
91 | |
92 | all without needing multiple fetches. |
34d52be2 |
93 | |
bfab575a |
94 | Only the helper methods for setting up standard relationship types |
d2113a68 |
95 | are documented here. For the basic, lower-level methods, and a description |
96 | of all the useful *_related methods that you get for free, see |
bfab575a |
97 | L<DBIx::Class::Relationship::Base>. |
503536d5 |
98 | |
34d52be2 |
99 | =head1 METHODS |
100 | |
bfab575a |
101 | All helper methods take the following arguments: |
503536d5 |
102 | |
8091aa91 |
103 | __PACKAGE__>$method_name('relname', 'Foreign::Class', $cond, $attrs); |
bfab575a |
104 | |
105 | Both C<$cond> and C<$attrs> are optional. Pass C<undef> for C<$cond> if |
106 | you want to use the default value for it, but still want to set C<$attrs>. |
2535b501 |
107 | |
9e64dfbf |
108 | See L<DBIx::Class::Relationship::Base> for a list of valid attributes and valid |
109 | relationship attributes. |
503536d5 |
110 | |
bfab575a |
111 | =head2 belongs_to |
503536d5 |
112 | |
2f3105ce |
113 | =over 4 |
114 | |
9e64dfbf |
115 | =item Arguments: $accessor_name, $related_class, $foreign_key_column|$cond?, $attr? |
2f3105ce |
116 | |
117 | =back |
118 | |
7a2c1380 |
119 | Creates a relationship where the calling class stores the foreign class's |
120 | primary key in one (or more) of its columns. This relationship defaults to |
121 | using C<$accessor_name> as the foreign key in C<$related_class> to resolve the |
122 | join, unless C<$foreign_key_column> specifies the foreign key column in |
123 | C<$related_class> or C<$cond> specifies a reference to a join condition hash. |
124 | |
125 | =over |
126 | |
127 | =item accessor_name |
128 | |
129 | This argument is the name of the method you can call on a |
130 | L<DBIx::Class::Row> object to retrieve the instance of the foreign |
131 | class matching this relationship. |
132 | |
133 | Use this accessor_name (relation name) in L<DBIx::Class::ResultSet/join> |
134 | or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table |
135 | indicated by this relationship. |
136 | |
137 | =item related_class |
138 | |
139 | This is the class name of the table referenced by the foreign key in |
140 | this class. |
141 | |
142 | =item foreign_key_column |
143 | |
144 | The column name on this class that contains the foreign key. |
145 | |
146 | OR |
147 | |
148 | =item cond |
149 | |
150 | A hashref where the keys are C<foreign.$column_on_related_table> and |
151 | the values are C<self.$foreign_key_column>. This is useful for |
152 | relations that are across multiple columns. |
153 | |
154 | =back |
155 | |
156 | |
c99393ff |
157 | # in a Book class (where Author has many Books) |
9e64dfbf |
158 | My::DBIC::Schema::Book->belongs_to( author => 'My::DBIC::Schema::Author' ); |
2535b501 |
159 | |
160 | my $author_obj = $obj->author; # get author object |
9e64dfbf |
161 | $obj->author( $new_author_obj ); # set author object |
162 | |
163 | The above belongs_to relationship could also have been specified as, |
2535b501 |
164 | |
9e64dfbf |
165 | My::DBIC::Schema::Book->belongs_to( author, |
166 | 'My::DBIC::Schema::Author', |
826daaae |
167 | { 'foreign.author' => 'self.author' } ); |
503536d5 |
168 | |
2f3105ce |
169 | If the relationship is optional -- i.e. the column containing the foreign key |
170 | can be NULL -- then the belongs_to relationship does the right thing. Thus, in |
171 | the example above C<$obj-E<gt>author> would return C<undef>. However in this |
172 | case you would probably want to set the C<join_type> attribute so that a C<LEFT |
173 | JOIN> is done, which makes complex resultsets involving C<join> or C<prefetch> |
174 | operations work correctly. The modified declaration is shown below: |
2c3ad870 |
175 | |
b8810cc5 |
176 | # in a Book class (where Author has_many Books) |
2c3ad870 |
177 | __PACKAGE__->belongs_to(author => 'My::DBIC::Schema::Author', |
178 | 'author', {join_type => 'left'}); |
179 | |
180 | |
b8810cc5 |
181 | Cascading deletes are off by default on a C<belongs_to> |
182 | relationship. To turn them on, pass C<< cascade_delete => 1 >> |
183 | in the $attr hashref. |
e8e9e5c7 |
184 | |
8091aa91 |
185 | NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent |
186 | of C<has_a>. |
503536d5 |
187 | |
9e64dfbf |
188 | See L<DBIx::Class::Relationship::Base> for documentation on relationship |
189 | methods and valid relationship attributes. |
2535b501 |
190 | |
bfab575a |
191 | =head2 has_many |
503536d5 |
192 | |
2f3105ce |
193 | =over 4 |
194 | |
2535b501 |
195 | =item Arguments: $accessor_name, $related_class, $foreign_key_column|$cond?, $attr? |
2f3105ce |
196 | |
197 | =back |
198 | |
7a2c1380 |
199 | Creates a one-to-many relationship, where the corresponding elements of the |
200 | foreign class store the calling class's primary key in one (or more) of its |
201 | columns. This relationship defaults to using C<$accessor_name> as the foreign |
202 | key in C<$related_class> to resolve the join, unless C<$foreign_key_column> |
203 | specifies the foreign key column in C<$related_class> or C<$cond> specifies a |
204 | reference to a join condition hash. |
205 | |
206 | =over |
207 | |
208 | =item accessor_name |
209 | |
210 | This argument is the name of the method you can call on a |
211 | L<DBIx::Class::Row> object to retrieve a resultset of the related |
212 | class restricted to the ones related to the row object. In list |
213 | context it returns the row objects. |
214 | |
215 | Use this accessor_name (relation name) in L<DBIx::Class::ResultSet/join> |
216 | or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table |
217 | indicated by this relationship. |
218 | |
219 | =item related_class |
220 | |
221 | This is the class name of the table which contains a foreign key |
222 | column containing PK values of this class. |
223 | |
224 | =item foreign_key_column |
225 | |
226 | The column name on the related class that contains the foreign key. |
227 | |
228 | OR |
229 | |
230 | =item cond |
231 | |
232 | A hashref where the keys are C<foreign.$column_on_related_table> and |
233 | the values are C<self.$foreign_key_column>. This is useful for |
234 | relations that are across multiple columns. |
235 | |
236 | =back |
237 | |
b8810cc5 |
238 | # in an Author class (where Author has_many Books) |
d2113a68 |
239 | My::DBIC::Schema::Author->has_many(books => 'My::DBIC::Schema::Book', 'author'); |
2535b501 |
240 | |
c99393ff |
241 | my $booklist = $obj->books; |
bc0c9800 |
242 | my $booklist = $obj->books({ |
243 | name => { LIKE => '%macaroni%' }, |
244 | { prefetch => [qw/book/], |
245 | }); |
c99393ff |
246 | my @book_objs = $obj->books; |
5b89a768 |
247 | my $books_rs = $obj->books; |
248 | ( $books_rs ) = $obj->books_rs; |
503536d5 |
249 | |
c99393ff |
250 | $obj->add_to_books(\%col_data); |
503536d5 |
251 | |
2535b501 |
252 | The above C<has_many> relationship could also have been specified with an |
253 | explicit join condition: |
254 | |
255 | My::DBIC::Schema::Author->has_many( books => 'My::DBIC::Schema::Book', { |
256 | 'foreign.author' => 'self.author', |
257 | }); |
258 | |
60a8fb95 |
259 | Three methods are created when you create a has_many relationship. The first |
2f3105ce |
260 | method is the expected accessor method, C<$accessor_name()>. The second is |
261 | almost exactly the same as the accessor method but "_rs" is added to the end of |
262 | the method name. This method works just like the normal accessor, except that |
263 | it returns a resultset no matter what, even in list context. The third method, |
2535b501 |
264 | named C<< add_to_$relname >>, will also be added to your Row items; this |
2f3105ce |
265 | allows you to insert new related items, using the same mechanism as in |
5b89a768 |
266 | L<DBIx::Class::Relationship::Base/"create_related">. |
d2113a68 |
267 | |
8091aa91 |
268 | If you delete an object in a class with a C<has_many> relationship, all |
b8810cc5 |
269 | the related objects will be deleted as well. To turn this behaviour off, |
270 | pass C<< cascade_delete => 0 >> in the C<$attr> hashref. However, any |
271 | database-level cascade or restrict will take precedence over a |
272 | DBIx-Class-based cascading delete. |
503536d5 |
273 | |
f4e92c39 |
274 | If you copy an object in a class with a C<has_many> relationship, all |
275 | the related objects will be copied as well. To turn this behaviour off, |
2fef093d |
276 | pass C<< cascade_copy => 0 >> in the C<$attr> hashref. The behaviour |
277 | defaults to C<< cascade_copy => 1 >>. |
f4e92c39 |
278 | |
9e64dfbf |
279 | See L<DBIx::Class::Relationship::Base> for documentation on relationship |
280 | methods and valid relationship attributes. |
2535b501 |
281 | |
bfab575a |
282 | =head2 might_have |
503536d5 |
283 | |
2f3105ce |
284 | =over 4 |
285 | |
9e64dfbf |
286 | =item Arguments: $accessor_name, $related_class, $foreign_key_column|$cond?, $attr? |
2f3105ce |
287 | |
288 | =back |
289 | |
7a2c1380 |
290 | Creates an optional one-to-one relationship with a class. This relationship |
291 | defaults to using C<$accessor_name> as the foreign key in C<$related_class> to |
292 | resolve the join, unless C<$foreign_key_column> specifies the foreign key |
293 | column in C<$related_class> or C<$cond> specifies a reference to a join |
294 | condition hash. |
295 | |
296 | =over |
297 | |
298 | =item accessor_name |
299 | |
300 | This argument is the name of the method you can call on a |
301 | L<DBIx::Class::Row> object to retrieve the instance of the foreign |
302 | class matching this relationship. |
303 | |
304 | Use this accessor_name (relation name) in L<DBIx::Class::ResultSet/join> |
305 | or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table |
306 | indicated by this relationship. |
307 | |
308 | =item related_class |
309 | |
310 | This is the class name of the table which contains a foreign key |
311 | column containing PK values of this class. |
312 | |
313 | =item foreign_key_column |
314 | |
315 | The column name on the related class that contains the foreign key. |
316 | |
317 | OR |
318 | |
319 | =item cond |
320 | |
321 | A hashref where the keys are C<foreign.$column_on_related_table> and |
322 | the values are C<self.$foreign_key_column>. This is useful for |
323 | relations that are across multiple columns. |
324 | |
325 | =back |
326 | |
9e64dfbf |
327 | My::DBIC::Schema::Author->might_have( pseudonym => |
328 | 'My::DBIC::Schema::Pseudonym' ); |
2f3105ce |
329 | |
880a1a0c |
330 | my $pname = $obj->pseudonym; # to get the Pseudonym object |
8091aa91 |
331 | |
9e64dfbf |
332 | The above might_have relationship could have been specified as: |
333 | |
334 | My::DBIC::Schema::Author->might_have( pseudonym => |
335 | 'My::DBIC::Schema::Pseudonym', |
336 | 'author' ); |
337 | |
338 | Or even: |
339 | |
340 | My::DBIC::Schema::Author->might_have( pseudonym => |
341 | 'My::DBIC::Schema::Pseudonym', |
342 | { 'foreign.author' => 'self.author' } ); |
343 | |
c99393ff |
344 | If you update or delete an object in a class with a C<might_have> |
b8810cc5 |
345 | relationship, the related object will be updated or deleted as well. To |
346 | turn off this behavior, add C<< cascade_delete => 0 >> to the C<$attr> |
347 | hashref. Any database-level update or delete constraints will override |
348 | this behavior. |
503536d5 |
349 | |
9e64dfbf |
350 | See L<DBIx::Class::Relationship::Base> for documentation on relationship |
351 | methods and valid relationship attributes. |
2f3105ce |
352 | |
bfab575a |
353 | =head2 has_one |
354 | |
2f3105ce |
355 | =over 4 |
356 | |
357 | =item Arguments: $accessor_name, $related_class_name, $join_condition?, $attr? |
358 | |
359 | =back |
360 | |
d2113a68 |
361 | My::DBIC::Schema::Book->has_one(isbn => 'My::DBIC::Schema::ISBN'); |
2f3105ce |
362 | |
363 | my $isbn_obj = $obj->isbn; # to get the ISBN object |
bfab575a |
364 | |
c99393ff |
365 | Creates a one-to-one relationship with another class. This is just like |
366 | C<might_have>, except the implication is that the other object is always |
367 | present. The only difference between C<has_one> and C<might_have> is that |
368 | C<has_one> uses an (ordinary) inner join, whereas C<might_have> uses a |
369 | left join. |
503536d5 |
370 | |
2f3105ce |
371 | The has_one relationship should be used when a row in the table has exactly one |
372 | related row in another table. If the related row might not exist in the foreign |
373 | table, use the L<DBIx::Class::Relationship/might_have> relationship. |
374 | |
375 | In the above example, each Book in the database is associated with exactly one |
376 | ISBN object. |
7411204b |
377 | |
9e64dfbf |
378 | See L<DBIx::Class::Relationship::Base> for documentation on relationship |
379 | methods and valid relationship attributes. |
87c4e602 |
380 | |
2535b501 |
381 | =head2 many_to_many |
2f3105ce |
382 | |
383 | =over 4 |
384 | |
2535b501 |
385 | =item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name, $attr? |
303cf522 |
386 | |
2f3105ce |
387 | =back |
388 | |
7a2c1380 |
389 | C<many_to_many> is not strictly a relationship in its own right. Instead, it is |
390 | a bridge between two resultsets which provide the same kind of convenience |
391 | accessors as true relationships provide. Although the accessor will return a |
392 | resultset or collection of objects just like has_many does, you cannot call |
393 | C<related_resultset> and similar methods which operate on true relationships. |
394 | |
395 | =over |
396 | |
397 | =item accessor_name |
398 | |
399 | This argument is the name of the method you can call on a |
400 | L<DBIx::Class::Row> object to retrieve the rows matching this |
401 | relationship. |
402 | |
403 | On a many_to_many, unlike other relationships, this cannot be used in |
404 | L<DBIx::Class::ResultSet/search> to join tables. Use the relations |
405 | bridged across instead. |
406 | |
407 | =item link_rel_name |
408 | |
409 | This is the accessor_name from the has_many relationship we are |
410 | bridging from. |
411 | |
412 | =item foreign_rel_name |
413 | |
414 | This is the accessor_name of the belongs_to relationship in the link |
415 | table that we are bridging across (which gives us the table we are |
416 | bridging to). |
417 | |
418 | =back |
419 | |
2f3105ce |
420 | To create a many_to_many relationship from Actor to Role: |
421 | |
75d07914 |
422 | My::DBIC::Schema::Actor->has_many( actor_roles => |
d2113a68 |
423 | 'My::DBIC::Schema::ActorRoles', |
424 | 'actor' ); |
75d07914 |
425 | My::DBIC::Schema::ActorRoles->belongs_to( role => |
d2113a68 |
426 | 'My::DBIC::Schema::Role' ); |
75d07914 |
427 | My::DBIC::Schema::ActorRoles->belongs_to( actor => |
d2113a68 |
428 | 'My::DBIC::Schema::Actor' ); |
429 | |
430 | My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles', |
71d5ed18 |
431 | 'role' ); |
bc0c9800 |
432 | |
2f3105ce |
433 | And, for the reverse relationship, from Role to Actor: |
434 | |
435 | My::DBIC::Schema::Role->has_many( actor_roles => |
436 | 'My::DBIC::Schema::ActorRoles', |
437 | 'role' ); |
438 | |
439 | My::DBIC::Schema::Role->many_to_many( actors => 'actor_roles', 'actor' ); |
440 | |
787d6a29 |
441 | To add a role for your actor, and fill in the year of the role in the |
442 | actor_roles table: |
443 | |
444 | $actor->add_to_roles($role, { year => 1995 }); |
445 | |
2535b501 |
446 | In the above example, ActorRoles is the link table class, and Role is the |
447 | foreign class. The C<$link_rel_name> parameter is the name of the accessor for |
448 | the has_many relationship from this table to the link table, and the |
449 | C<$foreign_rel_name> parameter is the accessor for the belongs_to relationship |
450 | from the link table to the foreign table. |
451 | |
d2113a68 |
452 | To use many_to_many, existing relationships from the original table to the link |
75d07914 |
453 | table, and from the link table to the end table must already exist, these |
d2113a68 |
454 | relation names are then used in the many_to_many call. |
7411204b |
455 | |
2535b501 |
456 | In the above example, the Actor class will have 3 many_to_many accessor methods |
2f3105ce |
457 | set: C<$roles>, C<$add_to_roles>, C<$set_roles>, and similarly named accessors |
2535b501 |
458 | will be created for the Role class for the C<actors> many_to_many |
459 | relationship. |
460 | |
9e64dfbf |
461 | See L<DBIx::Class::Relationship::Base> for documentation on relationship |
462 | methods and valid relationship attributes. |
2f3105ce |
463 | |
34d52be2 |
464 | =cut |
465 | |
b8e1e21f |
466 | 1; |
34d52be2 |
467 | |
34d52be2 |
468 | =head1 AUTHORS |
469 | |
daec44b8 |
470 | Matt S. Trout <mst@shadowcatsystems.co.uk> |
34d52be2 |
471 | |
472 | =head1 LICENSE |
473 | |
474 | You may distribute this code under the same terms as Perl itself. |
475 | |
476 | =cut |
477 | |