* Replaced eq_bind() implementation to use Test::Deep::eq_deeply().
[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 NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent
212 of C<has_a>.
213
214 See L<DBIx::Class::Relationship::Base> for documentation on relationship
215 methods and valid relationship attributes. Also see L<DBIx::Class::ResultSet>
216 for a L<list of standard resultset attributes|DBIx::Class::ResultSet/ATTRIBUTES>
217 which can be assigned to relationships as well.
218
219 =head2 has_many
220
221 =over 4
222
223 =item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond?, \%attr?
224
225 =back
226
227 Creates a one-to-many relationship, where the corresponding elements
228 of the foreign class store the calling class's primary key in one (or
229 more) of the foreign class columns. This relationship defaults to using
230 the end of this classes namespace as the foreign key in C<$related_class>
231 to resolve the join, unless C<$their_fk_column> specifies the foreign
232 key column in C<$related_class> or C<cond> specifies a reference to a
233 join condition hash.
234
235 =over
236
237 =item accessor_name
238
239 This argument is the name of the method you can call on a
240 L<DBIx::Class::Row> object to retrieve a resultset of the related
241 class restricted to the ones related to the row object. In list
242 context it returns the row objects. This is often called the
243 C<relation(ship) name>.
244
245 Use this accessor_name in L<DBIx::Class::ResultSet/join>
246 or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
247 indicated by this relationship.
248
249 =item related_class
250
251 This is the class name of the table which contains a foreign key
252 column containing PK values of this class.
253
254 =item their_fk_column
255
256 The column name on the related class that contains the foreign key.
257
258 OR
259
260 =item cond
261
262 A hashref where the keys are C<foreign.$their_fk_column> and
263 the values are C<self.$matching_column>. This is useful for
264 relations that are across multiple columns.
265
266 OR
267
268 An arrayref containing an SQL::Abstract-like condition. For example a
269 link table where two columns link back to the same table. This is an
270 OR condition.
271
272   My::Schema::Item->has_many('rels', 'My::Schema::Relationships',
273                              [ { 'foreign.LItemID' => 'self.ID' },
274                                { 'foreign.RItemID' => 'self.ID'} ]);
275
276 =back
277
278   # in an Author class (where Author has_many Books)
279   # assuming related class is storing our PK in "author_id"
280   My::DBIC::Schema::Author->has_many(
281     books => 
282     'My::DBIC::Schema::Book', 
283     'author_id'
284   );
285
286   # OR (same result)
287   My::DBIC::Schema::Author->has_many(
288     books => 
289     'My::DBIC::Schema::Book', 
290     { 'foreign.author_id' => 'self.id' },
291   );
292   
293   # OR (similar result, assuming related_class is storing our PK, in "author")
294   # (the "author" is guessed at from "Author" in the class namespace)
295   My::DBIC::Schema::Author->has_many(
296     books => 
297     'My::DBIC::Schema::Book', 
298   );
299
300
301   # Usage
302   # resultset of Books belonging to author 
303   my $booklist = $author->books;
304
305   # resultset of Books belonging to author, restricted by author name
306   my $booklist = $author->books({
307     name => { LIKE => '%macaroni%' },
308     { prefetch => [qw/book/],
309   });
310
311   # array of Book objects belonging to author
312   my @book_objs = $author->books;
313
314   # force resultset even in list context
315   my $books_rs = $author->books;
316   ( $books_rs ) = $obj->books_rs;
317
318   # create a new book for this author, the relation fields are auto-filled
319   $author->create_related('books', \%col_data);
320   # alternative method for the above
321   $author->add_to_books(\%col_data);
322
323
324 Three methods are created when you create a has_many relationship.  The first
325 method is the expected accessor method, C<$accessor_name()>.  The second is
326 almost exactly the same as the accessor method but "_rs" is added to the end of
327 the method name.  This method works just like the normal accessor, except that
328 it always returns a resultset, even in list context. The third method,
329 named C<< add_to_$relname >>, will also be added to your Row items; this
330 allows you to insert new related items, using the same mechanism as in
331 L<DBIx::Class::Relationship::Base/"create_related">.
332
333 If you delete an object in a class with a C<has_many> relationship, all
334 the related objects will be deleted as well.  To turn this behaviour off,
335 pass C<< cascade_delete => 0 >> in the C<$attr> hashref.
336
337 The cascaded operations are performed after the requested delete or
338 update, so if your database has a constraint on the relationship, it
339 will have deleted/updated the related records or raised an exception
340 before DBIx::Class gets to perform the cascaded operation.
341
342 If you copy an object in a class with a C<has_many> relationship, all
343 the related objects will be copied as well. To turn this behaviour off,
344 pass C<< cascade_copy => 0 >> in the C<$attr> hashref. The behaviour
345 defaults to C<< cascade_copy => 1 >>.
346
347 See L<DBIx::Class::Relationship::Base> for documentation on relationship
348 methods and valid relationship attributes. Also see L<DBIx::Class::ResultSet>
349 for a L<list of standard resultset attributes|DBIx::Class::ResultSet/ATTRIBUTES>
350 which can be assigned to relationships as well.
351
352 =head2 might_have
353
354 =over 4
355
356 =item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond?, \%attr?
357
358 =back
359
360 Creates an optional one-to-one relationship with a class. This relationship
361 defaults to using C<$accessor_name> as the foreign key in C<$related_class> to
362 resolve the join, unless C<$their_fk_column> specifies the foreign key
363 column in C<$related_class> or C<cond> specifies a reference to a join
364 condition hash.
365
366 =over
367
368 =item accessor_name
369
370 This argument is the name of the method you can call on a
371 L<DBIx::Class::Row> object to retrieve the instance of the foreign
372 class matching this relationship. This is often called the
373 C<relation(ship) name>.
374
375 Use this accessor_name in L<DBIx::Class::ResultSet/join>
376 or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
377 indicated by this relationship.
378
379 =item related_class
380
381 This is the class name of the table which contains a foreign key
382 column containing PK values of this class.
383
384 =item their_fk_column
385
386 The column name on the related class that contains the foreign key.
387
388 OR
389
390 =item cond
391
392 A hashref where the keys are C<foreign.$their_fk_column> and
393 the values are C<self.$matching_column>. This is useful for
394 relations that are across multiple columns.
395
396 =back
397
398   # Author may have an entry in the pseudonym table
399   My::DBIC::Schema::Author->might_have(
400     pseudonym =>
401     'My::DBIC::Schema::Pseudonym',
402     'author_id',
403   );
404
405   # OR (same result, assuming the related_class stores our PK)
406   My::DBIC::Schema::Author->might_have(
407     pseudonym =>
408     'My::DBIC::Schema::Pseudonym',
409   );
410
411   # OR (same result)
412   My::DBIC::Schema::Author->might_have(
413     pseudonym =>
414     'My::DBIC::Schema::Pseudonym',
415     { 'foreign.author_id' => 'self.id' },
416   );
417
418   # Usage
419   my $pname = $author->pseudonym; # to get the Pseudonym object
420
421 If you update or delete an object in a class with a C<might_have>
422 relationship, the related object will be updated or deleted as well. To
423 turn off this behavior, add C<< cascade_delete => 0 >> to the C<$attr>
424 hashref.
425
426 The cascaded operations are performed after the requested delete or
427 update, so if your database has a constraint on the relationship, it
428 will have deleted/updated the related records or raised an exception
429 before DBIx::Class gets to perform the cascaded operation.
430
431 See L<DBIx::Class::Relationship::Base> for documentation on relationship
432 methods and valid relationship attributes. Also see L<DBIx::Class::ResultSet>
433 for a L<list of standard resultset attributes|DBIx::Class::ResultSet/ATTRIBUTES>
434 which can be assigned to relationships as well.
435
436 =head2 has_one
437
438 =over 4
439
440 =item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond?, \%attr?
441
442 =back
443
444 Creates a one-to-one relationship with a class. This relationship
445 defaults to using C<$accessor_name> as the foreign key in C<$related_class> to
446 resolve the join, unless C<$their_fk_column> specifies the foreign key
447 column in C<$related_class> or C<cond> specifies a reference to a join
448 condition hash.
449
450 =over
451
452 =item accessor_name
453
454 This argument is the name of the method you can call on a
455 L<DBIx::Class::Row> object to retrieve the instance of the foreign
456 class matching this relationship. This is often called the
457 C<relation(ship) name>.
458
459 Use this accessor_name in L<DBIx::Class::ResultSet/join>
460 or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
461 indicated by this relationship.
462
463 =item related_class
464
465 This is the class name of the table which contains a foreign key
466 column containing PK values of this class.
467
468 =item their_fk_column
469
470 The column name on the related class that contains the foreign key.
471
472 OR
473
474 =item cond
475
476 A hashref where the keys are C<foreign.$their_fk_column> and
477 the values are C<self.$matching_column>. This is useful for
478 relations that are across multiple columns.
479
480 =back
481
482   # Every book has exactly one ISBN
483   My::DBIC::Schema::Book->has_one(
484     isbn => 
485     'My::DBIC::Schema::ISBN',
486     'book_id',
487   );
488
489   # OR (same result, assuming related_class stores our PK)
490   My::DBIC::Schema::Book->has_one(
491     isbn => 
492     'My::DBIC::Schema::ISBN',
493   );
494
495   # OR (same result)
496   My::DBIC::Schema::Book->has_one(
497     isbn => 
498     'My::DBIC::Schema::ISBN',
499     { 'foreign.book_id' => 'self.id' },
500   );
501
502   # Usage
503   my $isbn_obj = $book->isbn; # to get the ISBN object
504
505 Creates a one-to-one relationship with another class. This is just
506 like C<might_have>, except the implication is that the other object is
507 always present. The only difference between C<has_one> and
508 C<might_have> is that C<has_one> uses an (ordinary) inner join,
509 whereas C<might_have> defaults to a left join.
510
511 The has_one relationship should be used when a row in the table has exactly one
512 related row in another table. If the related row might not exist in the foreign
513 table, use the L<DBIx::Class::Relationship/might_have> relationship.
514
515 In the above example, each Book in the database is associated with exactly one
516 ISBN object.
517
518 See L<DBIx::Class::Relationship::Base> for documentation on relationship
519 methods and valid relationship attributes. Also see L<DBIx::Class::ResultSet>
520 for a L<list of standard resultset attributes|DBIx::Class::ResultSet/ATTRIBUTES>
521 which can be assigned to relationships as well.
522
523 =head2 many_to_many
524
525 =over 4
526
527 =item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name, \%attr?
528
529 =back
530
531 C<many_to_many> is not strictly a relationship in its own right. Instead, it is
532 a bridge between two resultsets which provide the same kind of convenience
533 accessors as true relationships provide. Although the accessor will return a 
534 resultset or collection of objects just like has_many does, you cannot call 
535 C<related_resultset> and similar methods which operate on true relationships.
536
537 =over
538
539 =item accessor_name
540
541 This argument is the name of the method you can call on a
542 L<DBIx::Class::Row> object to retrieve the rows matching this
543 relationship.
544
545 On a many_to_many, unlike other relationships, this cannot be used in
546 L<DBIx::Class::ResultSet/search> to join tables. Use the relations
547 bridged across instead.
548
549 =item link_rel_name
550
551 This is the accessor_name from the has_many relationship we are
552 bridging from.
553
554 =item foreign_rel_name
555
556 This is the accessor_name of the belongs_to relationship in the link
557 table that we are bridging across (which gives us the table we are
558 bridging to).
559
560 =back
561
562 To create a many_to_many relationship from Actor to Role:
563
564   My::DBIC::Schema::Actor->has_many( actor_roles =>
565                                      'My::DBIC::Schema::ActorRoles',
566                                      'actor' );
567   My::DBIC::Schema::ActorRoles->belongs_to( role =>
568                                             'My::DBIC::Schema::Role' );
569   My::DBIC::Schema::ActorRoles->belongs_to( actor =>
570                                             'My::DBIC::Schema::Actor' );
571
572   My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles',
573                                          'role' );
574
575 And, for the reverse relationship, from Role to Actor:
576
577   My::DBIC::Schema::Role->has_many( actor_roles =>
578                                     'My::DBIC::Schema::ActorRoles',
579                                     'role' );
580
581   My::DBIC::Schema::Role->many_to_many( actors => 'actor_roles', 'actor' );
582
583 To add a role for your actor, and fill in the year of the role in the
584 actor_roles table:
585
586   $actor->add_to_roles($role, { year => 1995 });
587
588 In the above example, ActorRoles is the link table class, and Role is the
589 foreign class. The C<$link_rel_name> parameter is the name of the accessor for
590 the has_many relationship from this table to the link table, and the
591 C<$foreign_rel_name> parameter is the accessor for the belongs_to relationship
592 from the link table to the foreign table.
593
594 To use many_to_many, existing relationships from the original table to the link
595 table, and from the link table to the end table must already exist, these
596 relation names are then used in the many_to_many call.
597
598 In the above example, the Actor class will have 3 many_to_many accessor methods
599 set: C<roles>, C<add_to_roles>, C<set_roles>, and similarly named accessors
600 will be created for the Role class for the C<actors> many_to_many
601 relationship.
602
603 See L<DBIx::Class::Relationship::Base> for documentation on relationship
604 methods and valid relationship attributes. Also see L<DBIx::Class::ResultSet>
605 for a L<list of standard resultset attributes|DBIx::Class::ResultSet/ATTRIBUTES>
606 which can be assigned to relationships as well.
607
608 =cut
609
610 1;
611
612 =head1 AUTHORS
613
614 see L<DBIx::Class>
615
616 =head1 LICENSE
617
618 You may distribute this code under the same terms as Perl itself.
619
620 =cut
621