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