Merge 'trunk' into 'sqla_1.50_compat'
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / Relationship.pm
1 package DBIx::Class::Relationship;
2
3 use strict;
4 use warnings;
5
6 use base qw/DBIx::Class/;
7
8 __PACKAGE__->load_own_components(qw/
9   Helpers
10   Accessor
11   CascadeActions
12   ProxyMethods
13   Base
14 /);
15
16 =head1 NAME
17
18 DBIx::Class::Relationship - Inter-table relationships
19
20 =head1 SYNOPSIS
21
22   ## Creating relationships
23   MyDB::Schema::Actor->has_many('actorroles' => 'MyDB::Schema::ActorRole',
24                                 'actor');
25   MyDB::Schema::Role->has_many('actorroles' => 'MyDB::Schema::ActorRole',
26                                 'role');
27   MyDB::Schema::ActorRole->belongs_to('role' => 'MyDB::Schema::Role');
28   MyDB::Schema::ActorRole->belongs_to('actor' => 'MyDB::Schema::Actor');
29
30   MyDB::Schema::Role->many_to_many('actors' => 'actorroles', 'actor');
31   MyDB::Schema::Actor->many_to_many('roles' => 'actorroles', 'role');
32
33   ## Using relationships
34   $schema->resultset('Actor')->find({ id => 1})->roles();
35   $schema->resultset('Role')->find({ id => 1 })->actorroles->search_related('actor', { Name => 'Fred' });
36   $schema->resultset('Actor')->add_to_roles({ Name => 'Sherlock Holmes'});
37
38 See L<DBIx::Class::Manual::Cookbook> for more.
39
40 =head1 DESCRIPTION
41
42 This class provides methods to set up relationships between the tables
43 in your database model. Relationships are the most useful and powerful
44 technique that L<DBIx::Class> provides. To create efficient database queries,
45 create relationships between any and all tables that have something in
46 common, for example if you have a table Authors:
47
48   ID  | Name | Age
49  ------------------
50    1  | Fred | 30
51    2  | Joe  | 32
52
53 and a table Books:
54
55   ID  | Author | Name
56  --------------------
57    1  |      1 | Rulers of the universe
58    2  |      1 | Rulers of the galaxy
59
60 Then without relationships, the method of getting all books by Fred goes like
61 this:
62
63  my $fred = $schema->resultset('Author')->find({ Name => 'Fred' });
64  my $fredsbooks = $schema->resultset('Book')->search({ Author => $fred->ID });
65
66 With a has_many relationship called "books" on Author (see below for details),
67 we can do this instead:
68
69  my $fredsbooks = $schema->resultset('Author')->find({ Name => 'Fred' })->books;
70
71 Each relationship sets up an accessor method on the
72 L<DBIx::Class::Manual::Glossary/"Row"> objects that represent the items
73 of your table. From L<DBIx::Class::Manual::Glossary/"ResultSet"> objects,
74 the relationships can be searched using the "search_related" method.
75 In list context, each returns a list of Row objects for the related class,
76 in scalar context, a new ResultSet representing the joined tables is
77 returned. Thus, the calls can be chained to produce complex queries.
78 Since the database is not actually queried until you attempt to retrieve
79 the data for an actual item, no time is wasted producing them.
80
81  my $cheapfredbooks = $schema->resultset('Author')->find({
82    Name => 'Fred',
83  })->books->search_related('prices', {
84    Price => { '<=' => '5.00' },
85  });
86
87 will produce a query something like:
88
89  SELECT * FROM Author me
90  LEFT JOIN Books books ON books.author = me.id
91  LEFT JOIN Prices prices ON prices.book = books.id
92  WHERE prices.Price <= 5.00
93
94 all without needing multiple fetches.
95
96 Only the helper methods for setting up standard relationship types
97 are documented here. For the basic, lower-level methods, and a description
98 of all the useful *_related methods that you get for free, see
99 L<DBIx::Class::Relationship::Base>.
100
101 =head1 METHODS
102
103 All helper methods are called similar to the following template:
104
105   __PACKAGE__->$method_name('relname', 'Foreign::Class', $cond, $attrs);
106   
107 Both C<$cond> and C<$attrs> are optional. Pass C<undef> for C<$cond> if
108 you want to use the default value for it, but still want to set C<$attrs>.
109
110 See L<DBIx::Class::Relationship::Base> for documentation on the
111 attrubutes that are allowed in the C<$attrs> argument.
112
113
114 =head2 belongs_to
115
116 =over 4
117
118 =item Arguments: $accessor_name, $related_class, $our_fk_column|\%cond|\@cond?, \%attr?
119
120 =back
121
122 Creates a relationship where the calling class stores the foreign
123 class's primary key in one (or more) of the calling class columns.
124 This relationship defaults to using C<$accessor_name> as the column
125 name in this class to resolve the join against the primary key from
126 C<$related_class>, unless C<$our_fk_column> specifies the foreign key column
127 in this class or C<cond> specifies a reference to a join condition hash.
128
129 =over
130
131 =item accessor_name
132
133 This argument is the name of the method you can call on a
134 L<DBIx::Class::Row> object to retrieve the instance of the foreign
135 class matching this relationship. This is often called the
136 C<relation(ship) name>.
137
138 Use this accessor_name in L<DBIx::Class::ResultSet/join>
139 or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
140 indicated by this relationship.
141
142 =item related_class
143
144 This is the class name of the table referenced by the foreign key in
145 this class.
146
147 =item our_fk_column
148
149 The column name on this class that contains the foreign key.
150
151 OR
152
153 =item cond
154
155 A hashref where the keys are C<foreign.$column_on_related_table> and
156 the values are C<self.$our_fk_column>. This is useful for
157 relations that are across multiple columns.
158
159 =back
160
161
162   # in a Book class (where Author has many Books)
163   My::DBIC::Schema::Book->belongs_to( 
164     author => 
165     'My::DBIC::Schema::Author', 
166     'author_id'
167   );
168
169   # OR (same result)
170   My::DBIC::Schema::Book->belongs_to(
171     author =>
172     'My::DBIC::Schema::Author',
173     { 'foreign.author_id' => 'self.author_id' } 
174   );
175
176   # OR (similar result but uglier accessor name)
177   My::DBIC::Schema::Book->belongs_to( 
178     author_id =>
179     'My::DBIC::Schema::Author'
180   );
181
182   # Usage
183   my $author_obj = $book->author; # get author object
184   $book->author( $new_author_obj ); # set author object
185   $book->author_id(); # get the plain id
186
187   # To retrieve the plain id if you used the ugly version:
188   $book->get_column('author_id');
189
190
191 If the relationship is optional -- i.e. the column containing the foreign key
192 can be NULL -- then the belongs_to relationship does the right thing. Thus, in
193 the example above C<$obj-E<gt>author> would return C<undef>.  However in this
194 case you would probably want to set the C<join_type> attribute so that a C<LEFT
195 JOIN> is done, which makes complex resultsets involving C<join> or C<prefetch>
196 operations work correctly.  The modified declaration is shown below:
197
198   # in a Book class (where Author has_many Books)
199   __PACKAGE__->belongs_to(
200     author => 
201     'My::DBIC::Schema::Author',
202     'author', 
203     { join_type => 'left' }
204   );
205
206
207 Cascading deletes are off by default on a C<belongs_to>
208 relationship. To turn them on, pass C<< cascade_delete => 1 >>
209 in the $attr hashref.
210
211 By default, DBIC will return undef and avoid querying the database if a
212 C<belongs_to> accessor is called when any part of the foreign key IS NULL. To
213 disable this behavior, pass C<< undef_on_null_fk => 0 >> in the C<$attr>
214 hashref.
215
216 NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent
217 of C<has_a>.
218
219 See L<DBIx::Class::Relationship::Base> for documentation on relationship
220 methods and valid relationship attributes. Also see L<DBIx::Class::ResultSet>
221 for a L<list of standard resultset attributes|DBIx::Class::ResultSet/ATTRIBUTES>
222 which can be assigned to relationships as well.
223
224 =head2 has_many
225
226 =over 4
227
228 =item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond?, \%attr?
229
230 =back
231
232 Creates a one-to-many relationship, where the corresponding elements
233 of the foreign class store the calling class's primary key in one (or
234 more) of the foreign class columns. This relationship defaults to using
235 the end of this classes namespace as the foreign key in C<$related_class>
236 to resolve the join, unless C<$their_fk_column> specifies the foreign
237 key column in C<$related_class> or C<cond> specifies a reference to a
238 join condition hash.
239
240 =over
241
242 =item accessor_name
243
244 This argument is the name of the method you can call on a
245 L<DBIx::Class::Row> object to retrieve a resultset of the related
246 class restricted to the ones related to the row object. In list
247 context it returns the row objects. This is often called the
248 C<relation(ship) name>.
249
250 Use this accessor_name in L<DBIx::Class::ResultSet/join>
251 or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
252 indicated by this relationship.
253
254 =item related_class
255
256 This is the class name of the table which contains a foreign key
257 column containing PK values of this class.
258
259 =item their_fk_column
260
261 The column name on the related class that contains the foreign key.
262
263 OR
264
265 =item cond
266
267 A hashref where the keys are C<foreign.$their_fk_column> and
268 the values are C<self.$matching_column>. This is useful for
269 relations that are across multiple columns.
270
271 OR
272
273 An arrayref containing an SQL::Abstract-like condition. For example a
274 link table where two columns link back to the same table. This is an
275 OR condition.
276
277   My::Schema::Item->has_many('rels', 'My::Schema::Relationships',
278                              [ { 'foreign.LItemID' => 'self.ID' },
279                                { 'foreign.RItemID' => 'self.ID'} ]);
280
281 =back
282
283   # in an Author class (where Author has_many Books)
284   # assuming related class is storing our PK in "author_id"
285   My::DBIC::Schema::Author->has_many(
286     books => 
287     'My::DBIC::Schema::Book', 
288     'author_id'
289   );
290
291   # OR (same result)
292   My::DBIC::Schema::Author->has_many(
293     books => 
294     'My::DBIC::Schema::Book', 
295     { 'foreign.author_id' => 'self.id' },
296   );
297   
298   # OR (similar result, assuming related_class is storing our PK, in "author")
299   # (the "author" is guessed at from "Author" in the class namespace)
300   My::DBIC::Schema::Author->has_many(
301     books => 
302     'My::DBIC::Schema::Book', 
303   );
304
305
306   # Usage
307   # resultset of Books belonging to author 
308   my $booklist = $author->books;
309
310   # resultset of Books belonging to author, restricted by author name
311   my $booklist = $author->books({
312     name => { LIKE => '%macaroni%' },
313     { prefetch => [qw/book/],
314   });
315
316   # array of Book objects belonging to author
317   my @book_objs = $author->books;
318
319   # force resultset even in list context
320   my $books_rs = $author->books;
321   ( $books_rs ) = $obj->books_rs;
322
323   # create a new book for this author, the relation fields are auto-filled
324   $author->create_related('books', \%col_data);
325   # alternative method for the above
326   $author->add_to_books(\%col_data);
327
328
329 Three methods are created when you create a has_many relationship.  The first
330 method is the expected accessor method, C<$accessor_name()>.  The second is
331 almost exactly the same as the accessor method but "_rs" is added to the end of
332 the method name.  This method works just like the normal accessor, except that
333 it always returns a resultset, even in list context. The third method,
334 named C<< add_to_$relname >>, will also be added to your Row items; this
335 allows you to insert new related items, using the same mechanism as in
336 L<DBIx::Class::Relationship::Base/"create_related">.
337
338 If you delete an object in a class with a C<has_many> relationship, all
339 the related objects will be deleted as well.  To turn this behaviour off,
340 pass C<< cascade_delete => 0 >> in the C<$attr> hashref.
341
342 The cascaded operations are performed after the requested delete or
343 update, so if your database has a constraint on the relationship, it
344 will have deleted/updated the related records or raised an exception
345 before DBIx::Class gets to perform the cascaded operation.
346
347 If you copy an object in a class with a C<has_many> relationship, all
348 the related objects will be copied as well. To turn this behaviour off,
349 pass C<< cascade_copy => 0 >> in the C<$attr> hashref. The behaviour
350 defaults to C<< cascade_copy => 1 >>.
351
352 See L<DBIx::Class::Relationship::Base> for documentation on relationship
353 methods and valid relationship attributes. Also see L<DBIx::Class::ResultSet>
354 for a L<list of standard resultset attributes|DBIx::Class::ResultSet/ATTRIBUTES>
355 which can be assigned to relationships as well.
356
357 =head2 might_have
358
359 =over 4
360
361 =item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond?, \%attr?
362
363 =back
364
365 Creates an optional one-to-one relationship with a class. This relationship
366 defaults to using C<$accessor_name> as the foreign key in C<$related_class> to
367 resolve the join, unless C<$their_fk_column> specifies the foreign key
368 column in C<$related_class> or C<cond> specifies a reference to a join
369 condition hash.
370
371 =over
372
373 =item accessor_name
374
375 This argument is the name of the method you can call on a
376 L<DBIx::Class::Row> object to retrieve the instance of the foreign
377 class matching this relationship. This is often called the
378 C<relation(ship) name>.
379
380 Use this accessor_name in L<DBIx::Class::ResultSet/join>
381 or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
382 indicated by this relationship.
383
384 =item related_class
385
386 This is the class name of the table which contains a foreign key
387 column containing PK values of this class.
388
389 =item their_fk_column
390
391 The column name on the related class that contains the foreign key.
392
393 OR
394
395 =item cond
396
397 A hashref where the keys are C<foreign.$their_fk_column> and
398 the values are C<self.$matching_column>. This is useful for
399 relations that are across multiple columns.
400
401 =back
402
403   # Author may have an entry in the pseudonym table
404   My::DBIC::Schema::Author->might_have(
405     pseudonym =>
406     'My::DBIC::Schema::Pseudonym',
407     'author_id',
408   );
409
410   # OR (same result, assuming the related_class stores our PK)
411   My::DBIC::Schema::Author->might_have(
412     pseudonym =>
413     'My::DBIC::Schema::Pseudonym',
414   );
415
416   # OR (same result)
417   My::DBIC::Schema::Author->might_have(
418     pseudonym =>
419     'My::DBIC::Schema::Pseudonym',
420     { 'foreign.author_id' => 'self.id' },
421   );
422
423   # Usage
424   my $pname = $author->pseudonym; # to get the Pseudonym object
425
426 If you update or delete an object in a class with a C<might_have>
427 relationship, the related object will be updated or deleted as well. To
428 turn off this behavior, add C<< cascade_delete => 0 >> to the C<$attr>
429 hashref.
430
431 The cascaded operations are performed after the requested delete or
432 update, so if your database has a constraint on the relationship, it
433 will have deleted/updated the related records or raised an exception
434 before DBIx::Class gets to perform the cascaded operation.
435
436 See L<DBIx::Class::Relationship::Base> for documentation on relationship
437 methods and valid relationship attributes. Also see L<DBIx::Class::ResultSet>
438 for a L<list of standard resultset attributes|DBIx::Class::ResultSet/ATTRIBUTES>
439 which can be assigned to relationships as well.
440
441 =head2 has_one
442
443 =over 4
444
445 =item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond?, \%attr?
446
447 =back
448
449 Creates a one-to-one relationship with a class. This relationship
450 defaults to using C<$accessor_name> as the foreign key in C<$related_class> to
451 resolve the join, unless C<$their_fk_column> specifies the foreign key
452 column in C<$related_class> or C<cond> specifies a reference to a join
453 condition hash.
454
455 =over
456
457 =item accessor_name
458
459 This argument is the name of the method you can call on a
460 L<DBIx::Class::Row> object to retrieve the instance of the foreign
461 class matching this relationship. This is often called the
462 C<relation(ship) name>.
463
464 Use this accessor_name in L<DBIx::Class::ResultSet/join>
465 or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
466 indicated by this relationship.
467
468 =item related_class
469
470 This is the class name of the table which contains a foreign key
471 column containing PK values of this class.
472
473 =item their_fk_column
474
475 The column name on the related class that contains the foreign key.
476
477 OR
478
479 =item cond
480
481 A hashref where the keys are C<foreign.$their_fk_column> and
482 the values are C<self.$matching_column>. This is useful for
483 relations that are across multiple columns.
484
485 =back
486
487   # Every book has exactly one ISBN
488   My::DBIC::Schema::Book->has_one(
489     isbn => 
490     'My::DBIC::Schema::ISBN',
491     'book_id',
492   );
493
494   # OR (same result, assuming related_class stores our PK)
495   My::DBIC::Schema::Book->has_one(
496     isbn => 
497     'My::DBIC::Schema::ISBN',
498   );
499
500   # OR (same result)
501   My::DBIC::Schema::Book->has_one(
502     isbn => 
503     'My::DBIC::Schema::ISBN',
504     { 'foreign.book_id' => 'self.id' },
505   );
506
507   # Usage
508   my $isbn_obj = $book->isbn; # to get the ISBN object
509
510 Creates a one-to-one relationship with another class. This is just
511 like C<might_have>, except the implication is that the other object is
512 always present. The only difference between C<has_one> and
513 C<might_have> is that C<has_one> uses an (ordinary) inner join,
514 whereas C<might_have> defaults to a left join.
515
516 The has_one relationship should be used when a row in the table has exactly one
517 related row in another table. If the related row might not exist in the foreign
518 table, use the L<DBIx::Class::Relationship/might_have> relationship.
519
520 In the above example, each Book in the database is associated with exactly one
521 ISBN object.
522
523 See L<DBIx::Class::Relationship::Base> for documentation on relationship
524 methods and valid relationship attributes. Also see L<DBIx::Class::ResultSet>
525 for a L<list of standard resultset attributes|DBIx::Class::ResultSet/ATTRIBUTES>
526 which can be assigned to relationships as well.
527
528 =head2 many_to_many
529
530 =over 4
531
532 =item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name, \%attr?
533
534 =back
535
536 C<many_to_many> is not strictly a relationship in its own right. Instead, it is
537 a bridge between two resultsets which provide the same kind of convenience
538 accessors as true relationships provide. Although the accessor will return a 
539 resultset or collection of objects just like has_many does, you cannot call 
540 C<related_resultset> and similar methods which operate on true relationships.
541
542 =over
543
544 =item accessor_name
545
546 This argument is the name of the method you can call on a
547 L<DBIx::Class::Row> object to retrieve the rows matching this
548 relationship.
549
550 On a many_to_many, unlike other relationships, this cannot be used in
551 L<DBIx::Class::ResultSet/search> to join tables. Use the relations
552 bridged across instead.
553
554 =item link_rel_name
555
556 This is the accessor_name from the has_many relationship we are
557 bridging from.
558
559 =item foreign_rel_name
560
561 This is the accessor_name of the belongs_to relationship in the link
562 table that we are bridging across (which gives us the table we are
563 bridging to).
564
565 =back
566
567 To create a many_to_many relationship from Actor to Role:
568
569   My::DBIC::Schema::Actor->has_many( actor_roles =>
570                                      'My::DBIC::Schema::ActorRoles',
571                                      'actor' );
572   My::DBIC::Schema::ActorRoles->belongs_to( role =>
573                                             'My::DBIC::Schema::Role' );
574   My::DBIC::Schema::ActorRoles->belongs_to( actor =>
575                                             'My::DBIC::Schema::Actor' );
576
577   My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles',
578                                          'role' );
579
580 And, for the reverse relationship, from Role to Actor:
581
582   My::DBIC::Schema::Role->has_many( actor_roles =>
583                                     'My::DBIC::Schema::ActorRoles',
584                                     'role' );
585
586   My::DBIC::Schema::Role->many_to_many( actors => 'actor_roles', 'actor' );
587
588 To add a role for your actor, and fill in the year of the role in the
589 actor_roles table:
590
591   $actor->add_to_roles($role, { year => 1995 });
592
593 In the above example, ActorRoles is the link table class, and Role is the
594 foreign class. The C<$link_rel_name> parameter is the name of the accessor for
595 the has_many relationship from this table to the link table, and the
596 C<$foreign_rel_name> parameter is the accessor for the belongs_to relationship
597 from the link table to the foreign table.
598
599 To use many_to_many, existing relationships from the original table to the link
600 table, and from the link table to the end table must already exist, these
601 relation names are then used in the many_to_many call.
602
603 In the above example, the Actor class will have 3 many_to_many accessor methods
604 set: C<roles>, C<add_to_roles>, C<set_roles>, and similarly named accessors
605 will be created for the Role class for the C<actors> many_to_many
606 relationship.
607
608 See L<DBIx::Class::Relationship::Base> for documentation on relationship
609 methods and valid relationship attributes. Also see L<DBIx::Class::ResultSet>
610 for a L<list of standard resultset attributes|DBIx::Class::ResultSet/ATTRIBUTES>
611 which can be assigned to relationships as well.
612
613 =cut
614
615 1;
616
617 =head1 AUTHORS
618
619 see L<DBIx::Class>
620
621 =head1 LICENSE
622
623 You may distribute this code under the same terms as Perl itself.
624
625 =cut
626