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