Merge 'bulk_create' into 'DBIx-Class-current'
[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
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
36See L<DBIx::Class::Manual::Cookbook> for more.
37
34d52be2 38=head1 DESCRIPTION
39
bc1171c3 40This class provides methods to set up relationships between the tables
41in your database model. Relationships are the most useful and powerful
42technique that L<DBIx::Class> provides. To create efficient database queries,
43create relationships between any and all tables that have something in
44common, for example if you have a table Authors:
45
46 ID | Name | Age
47 ------------------
48 1 | Fred | 30
49 2 | Joe | 32
50
51and a table Books:
52
53 ID | Author | Name
54 --------------------
55 1 | 1 | Rulers of the universe
56 2 | 1 | Rulers of the galaxy
57
58Then without relationships, the method of getting all books by Fred goes like
59this:
60
61 my $fred = $schema->resultset('Author')->find({ Name => 'Fred' });
62 my $fredsbooks = $schema->resultset('Book')->search({ Author => $fred->ID });
63With a has_many relationship called "books" on Author (see below for details),
64we can do this instead:
65
66 my $fredsbooks = $schema->resultset('Author')->find({ Name => 'Fred' })->books;
67
75d07914 68Each relationship sets up an accessor method on the
bc1171c3 69L<DBIx::Class::Manual::Glossary/"Row"> objects that represent the items
70of your table. From L<DBIx::Class::Manual::Glossary/"ResultSet"> objects,
75d07914 71the relationships can be searched using the "search_related" method.
bc1171c3 72In list context, each returns a list of Row objects for the related class,
73in scalar context, a new ResultSet representing the joined tables is
74returned. Thus, the calls can be chained to produce complex queries.
75Since the database is not actually queried until you attempt to retrieve
76the data for an actual item, no time is wasted producing them.
77
bc0c9800 78 my $cheapfredbooks = $schema->resultset('Author')->find({
79 Name => 'Fred',
80 })->books->search_related('prices', {
81 Price => { '<=' => '5.00' },
82 });
bc1171c3 83
84will produce a query something like:
85
75d07914 86 SELECT * FROM Author me
bc1171c3 87 LEFT JOIN Books books ON books.author = me.id
88 LEFT JOIN Prices prices ON prices.book = books.id
89 WHERE prices.Price <= 5.00
90
91all without needing multiple fetches.
34d52be2 92
bfab575a 93Only the helper methods for setting up standard relationship types
d2113a68 94are documented here. For the basic, lower-level methods, and a description
95of all the useful *_related methods that you get for free, see
bfab575a 96L<DBIx::Class::Relationship::Base>.
503536d5 97
34d52be2 98=head1 METHODS
99
bfab575a 100All helper methods take the following arguments:
503536d5 101
8091aa91 102 __PACKAGE__>$method_name('relname', 'Foreign::Class', $cond, $attrs);
bfab575a 103
104Both C<$cond> and C<$attrs> are optional. Pass C<undef> for C<$cond> if
105you want to use the default value for it, but still want to set C<$attrs>.
2535b501 106
9e64dfbf 107See L<DBIx::Class::Relationship::Base> for a list of valid attributes and valid
108relationship attributes.
503536d5 109
bfab575a 110=head2 belongs_to
503536d5 111
2f3105ce 112=over 4
113
9e64dfbf 114=item Arguments: $accessor_name, $related_class, $foreign_key_column|$cond?, $attr?
2f3105ce 115
116=back
117
c99393ff 118 # in a Book class (where Author has many Books)
9e64dfbf 119 My::DBIC::Schema::Book->belongs_to( author => 'My::DBIC::Schema::Author' );
2535b501 120
121 my $author_obj = $obj->author; # get author object
9e64dfbf 122 $obj->author( $new_author_obj ); # set author object
123
124The above belongs_to relationship could also have been specified as,
2535b501 125
9e64dfbf 126 My::DBIC::Schema::Book->belongs_to( author,
127 'My::DBIC::Schema::Author',
826daaae 128 { 'foreign.author' => 'self.author' } );
503536d5 129
75d07914 130Creates a relationship where the calling class stores the foreign class's
9e64dfbf 131primary key in one (or more) of its columns. This relationship defaults to
132using C<$accessor_name> as the foreign key in C<$related_class> to resolve the
133join, unless C<$foreign_key_column> specifies the foreign key column in
134C<$related_class> or C<$cond> specifies a reference to a join condition hash.
2f3105ce 135
136If the relationship is optional -- i.e. the column containing the foreign key
137can be NULL -- then the belongs_to relationship does the right thing. Thus, in
138the example above C<$obj-E<gt>author> would return C<undef>. However in this
139case you would probably want to set the C<join_type> attribute so that a C<LEFT
140JOIN> is done, which makes complex resultsets involving C<join> or C<prefetch>
141operations work correctly. The modified declaration is shown below:
2c3ad870 142
b8810cc5 143 # in a Book class (where Author has_many Books)
2c3ad870 144 __PACKAGE__->belongs_to(author => 'My::DBIC::Schema::Author',
145 'author', {join_type => 'left'});
146
147
b8810cc5 148Cascading deletes are off by default on a C<belongs_to>
149relationship. To turn them on, pass C<< cascade_delete => 1 >>
150in the $attr hashref.
e8e9e5c7 151
8091aa91 152NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent
153of C<has_a>.
503536d5 154
9e64dfbf 155See L<DBIx::Class::Relationship::Base> for documentation on relationship
156methods and valid relationship attributes.
2535b501 157
bfab575a 158=head2 has_many
503536d5 159
2f3105ce 160=over 4
161
2535b501 162=item Arguments: $accessor_name, $related_class, $foreign_key_column|$cond?, $attr?
2f3105ce 163
164=back
165
b8810cc5 166 # in an Author class (where Author has_many Books)
d2113a68 167 My::DBIC::Schema::Author->has_many(books => 'My::DBIC::Schema::Book', 'author');
2535b501 168
c99393ff 169 my $booklist = $obj->books;
bc0c9800 170 my $booklist = $obj->books({
171 name => { LIKE => '%macaroni%' },
172 { prefetch => [qw/book/],
173 });
c99393ff 174 my @book_objs = $obj->books;
5b89a768 175 my $books_rs = $obj->books;
176 ( $books_rs ) = $obj->books_rs;
503536d5 177
c99393ff 178 $obj->add_to_books(\%col_data);
503536d5 179
2535b501 180The above C<has_many> relationship could also have been specified with an
181explicit join condition:
182
183 My::DBIC::Schema::Author->has_many( books => 'My::DBIC::Schema::Book', {
184 'foreign.author' => 'self.author',
185 });
186
8091aa91 187Creates a one-to-many relationship, where the corresponding elements of the
188foreign class store the calling class's primary key in one (or more) of its
9e64dfbf 189columns. This relationship defaults to using C<$accessor_name> as the foreign
190key in C<$related_class> to resolve the join, unless C<$foreign_key_column>
191specifies the foreign key column in C<$related_class> or C<$cond> specifies a
192reference to a join condition hash.
8091aa91 193
60a8fb95 194Three methods are created when you create a has_many relationship. The first
2f3105ce 195method is the expected accessor method, C<$accessor_name()>. The second is
196almost exactly the same as the accessor method but "_rs" is added to the end of
197the method name. This method works just like the normal accessor, except that
198it returns a resultset no matter what, even in list context. The third method,
2535b501 199named C<< add_to_$relname >>, will also be added to your Row items; this
2f3105ce 200allows you to insert new related items, using the same mechanism as in
5b89a768 201L<DBIx::Class::Relationship::Base/"create_related">.
d2113a68 202
8091aa91 203If you delete an object in a class with a C<has_many> relationship, all
b8810cc5 204the related objects will be deleted as well. To turn this behaviour off,
205pass C<< cascade_delete => 0 >> in the C<$attr> hashref. However, any
206database-level cascade or restrict will take precedence over a
207DBIx-Class-based cascading delete.
503536d5 208
9e64dfbf 209See L<DBIx::Class::Relationship::Base> for documentation on relationship
210methods and valid relationship attributes.
2535b501 211
bfab575a 212=head2 might_have
503536d5 213
2f3105ce 214=over 4
215
9e64dfbf 216=item Arguments: $accessor_name, $related_class, $foreign_key_column|$cond?, $attr?
2f3105ce 217
218=back
219
9e64dfbf 220 My::DBIC::Schema::Author->might_have( pseudonym =>
221 'My::DBIC::Schema::Pseudonym' );
2f3105ce 222
880a1a0c 223 my $pname = $obj->pseudonym; # to get the Pseudonym object
8091aa91 224
9e64dfbf 225The above might_have relationship could have been specified as:
226
227 My::DBIC::Schema::Author->might_have( pseudonym =>
228 'My::DBIC::Schema::Pseudonym',
229 'author' );
230
231Or even:
232
233 My::DBIC::Schema::Author->might_have( pseudonym =>
234 'My::DBIC::Schema::Pseudonym',
235 { 'foreign.author' => 'self.author' } );
236
237Assuming the Pseudonym table has
238
2f3105ce 239Creates an optional one-to-one relationship with a class. This relationship
9e64dfbf 240defaults to using C<$accessor_name> as the foreign key in C<$related_class> to
241resolve the join, unless C<$foreign_key_column> specifies the foreign key
242column in C<$related_class> or C<$cond> specifies a reference to a join
243condition hash.
503536d5 244
c99393ff 245If you update or delete an object in a class with a C<might_have>
b8810cc5 246relationship, the related object will be updated or deleted as well. To
247turn off this behavior, add C<< cascade_delete => 0 >> to the C<$attr>
248hashref. Any database-level update or delete constraints will override
249this behavior.
503536d5 250
9e64dfbf 251See L<DBIx::Class::Relationship::Base> for documentation on relationship
252methods and valid relationship attributes.
2f3105ce 253
bfab575a 254=head2 has_one
255
2f3105ce 256=over 4
257
258=item Arguments: $accessor_name, $related_class_name, $join_condition?, $attr?
259
260=back
261
d2113a68 262 My::DBIC::Schema::Book->has_one(isbn => 'My::DBIC::Schema::ISBN');
2f3105ce 263
264 my $isbn_obj = $obj->isbn; # to get the ISBN object
bfab575a 265
c99393ff 266Creates a one-to-one relationship with another class. This is just like
267C<might_have>, except the implication is that the other object is always
268present. The only difference between C<has_one> and C<might_have> is that
269C<has_one> uses an (ordinary) inner join, whereas C<might_have> uses a
270left join.
503536d5 271
2f3105ce 272The has_one relationship should be used when a row in the table has exactly one
273related row in another table. If the related row might not exist in the foreign
274table, use the L<DBIx::Class::Relationship/might_have> relationship.
275
276In the above example, each Book in the database is associated with exactly one
277ISBN object.
7411204b 278
9e64dfbf 279See L<DBIx::Class::Relationship::Base> for documentation on relationship
280methods and valid relationship attributes.
87c4e602 281
2535b501 282=head2 many_to_many
2f3105ce 283
284=over 4
285
2535b501 286=item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name, $attr?
303cf522 287
2f3105ce 288=back
289
290To create a many_to_many relationship from Actor to Role:
291
75d07914 292 My::DBIC::Schema::Actor->has_many( actor_roles =>
d2113a68 293 'My::DBIC::Schema::ActorRoles',
294 'actor' );
75d07914 295 My::DBIC::Schema::ActorRoles->belongs_to( role =>
d2113a68 296 'My::DBIC::Schema::Role' );
75d07914 297 My::DBIC::Schema::ActorRoles->belongs_to( actor =>
d2113a68 298 'My::DBIC::Schema::Actor' );
299
300 My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles',
71d5ed18 301 'role' );
bc0c9800 302
2f3105ce 303And, for the reverse relationship, from Role to Actor:
304
305 My::DBIC::Schema::Role->has_many( actor_roles =>
306 'My::DBIC::Schema::ActorRoles',
307 'role' );
308
309 My::DBIC::Schema::Role->many_to_many( actors => 'actor_roles', 'actor' );
310
787d6a29 311To add a role for your actor, and fill in the year of the role in the
312actor_roles table:
313
314 $actor->add_to_roles($role, { year => 1995 });
315
a693b319 316Many_to_many is not strictly a relationship in its own right. Instead, it is
317a bridge between two resultsets which provide the same kind of convenience
318accessors as true relationships provide. Although the accessor will return a
319resultset or collection of objects just like has_many does, you cannot call
320C<$related_resultset> and similar methods which operate on true relationships.
b8eca5ce 321
2535b501 322In the above example, ActorRoles is the link table class, and Role is the
323foreign class. The C<$link_rel_name> parameter is the name of the accessor for
324the has_many relationship from this table to the link table, and the
325C<$foreign_rel_name> parameter is the accessor for the belongs_to relationship
326from the link table to the foreign table.
327
d2113a68 328To use many_to_many, existing relationships from the original table to the link
75d07914 329table, and from the link table to the end table must already exist, these
d2113a68 330relation names are then used in the many_to_many call.
7411204b 331
2535b501 332In the above example, the Actor class will have 3 many_to_many accessor methods
2f3105ce 333set: C<$roles>, C<$add_to_roles>, C<$set_roles>, and similarly named accessors
2535b501 334will be created for the Role class for the C<actors> many_to_many
335relationship.
336
9e64dfbf 337See L<DBIx::Class::Relationship::Base> for documentation on relationship
338methods and valid relationship attributes.
2f3105ce 339
34d52be2 340=cut
341
b8e1e21f 3421;
34d52be2 343
34d52be2 344=head1 AUTHORS
345
daec44b8 346Matt S. Trout <mst@shadowcatsystems.co.uk>
34d52be2 347
348=head1 LICENSE
349
350You may distribute this code under the same terms as Perl itself.
351
352=cut
353