Commit | Line | Data |
b8e1e21f |
1 | package DBIx::Class::Relationship; |
2 | |
3 | use strict; |
4 | use warnings; |
5 | |
1edd1722 |
6 | use 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 | |
18 | DBIx::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 | |
36 | See L<DBIx::Class::Manual::Cookbook> for more. |
37 | |
34d52be2 |
38 | =head1 DESCRIPTION |
39 | |
bc1171c3 |
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 | |
75d07914 |
68 | Each relationship sets up an accessor method on the |
bc1171c3 |
69 | L<DBIx::Class::Manual::Glossary/"Row"> objects that represent the items |
70 | of your table. From L<DBIx::Class::Manual::Glossary/"ResultSet"> objects, |
75d07914 |
71 | the relationships can be searched using the "search_related" method. |
bc1171c3 |
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 | |
bc0c9800 |
78 | my $cheapfredbooks = $schema->resultset('Author')->find({ |
79 | Name => 'Fred', |
80 | })->books->search_related('prices', { |
81 | Price => { '<=' => '5.00' }, |
82 | }); |
bc1171c3 |
83 | |
84 | will 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 | |
91 | all without needing multiple fetches. |
34d52be2 |
92 | |
bfab575a |
93 | Only the helper methods for setting up standard relationship types |
d2113a68 |
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 |
bfab575a |
96 | L<DBIx::Class::Relationship::Base>. |
503536d5 |
97 | |
34d52be2 |
98 | =head1 METHODS |
99 | |
bfab575a |
100 | All helper methods take the following arguments: |
503536d5 |
101 | |
8091aa91 |
102 | __PACKAGE__>$method_name('relname', 'Foreign::Class', $cond, $attrs); |
bfab575a |
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>. |
2535b501 |
106 | |
8091aa91 |
107 | See L<DBIx::Class::Relationship::Base> for a list of valid attributes. |
503536d5 |
108 | |
bfab575a |
109 | =head2 belongs_to |
503536d5 |
110 | |
2f3105ce |
111 | =over 4 |
112 | |
113 | =item Arguments: $accessor_name, $related_class, $foreign_key_column?, $attr? |
114 | |
115 | =back |
116 | |
c99393ff |
117 | # in a Book class (where Author has many Books) |
d2113a68 |
118 | My::DBIC::Schema::Book->belongs_to(author => 'My::DBIC::Schema::Author'); |
2535b501 |
119 | |
120 | my $author_obj = $obj->author; # get author object |
121 | $obj->author($new_author_obj); # set author object |
122 | |
123 | My::DBIC::Schema::Book->belongs_to(publisher => |
503536d5 |
124 | |
75d07914 |
125 | Creates a relationship where the calling class stores the foreign class's |
b8810cc5 |
126 | primary key in one (or more) of its columns. If C<$cond> is a column name |
2f3105ce |
127 | instead of a join condition hash, it is used as the name of the foreign key |
128 | column in the calling class. If C<$cond> is not given, C<$accessor_name> is |
129 | used as the column name. |
130 | |
131 | If the relationship is optional -- i.e. the column containing the foreign key |
132 | can be NULL -- then the belongs_to relationship does the right thing. Thus, in |
133 | the example above C<$obj-E<gt>author> would return C<undef>. However in this |
134 | case you would probably want to set the C<join_type> attribute so that a C<LEFT |
135 | JOIN> is done, which makes complex resultsets involving C<join> or C<prefetch> |
136 | operations work correctly. The modified declaration is shown below: |
2c3ad870 |
137 | |
b8810cc5 |
138 | # in a Book class (where Author has_many Books) |
2c3ad870 |
139 | __PACKAGE__->belongs_to(author => 'My::DBIC::Schema::Author', |
140 | 'author', {join_type => 'left'}); |
141 | |
142 | |
b8810cc5 |
143 | Cascading deletes are off by default on a C<belongs_to> |
144 | relationship. To turn them on, pass C<< cascade_delete => 1 >> |
145 | in the $attr hashref. |
e8e9e5c7 |
146 | |
8091aa91 |
147 | NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent |
148 | of C<has_a>. |
503536d5 |
149 | |
2535b501 |
150 | See L<DBIx::Class::Relationship::Base> for documentation on relationship methods. |
151 | |
bfab575a |
152 | =head2 has_many |
503536d5 |
153 | |
2f3105ce |
154 | =over 4 |
155 | |
2535b501 |
156 | =item Arguments: $accessor_name, $related_class, $foreign_key_column|$cond?, $attr? |
2f3105ce |
157 | |
158 | =back |
159 | |
b8810cc5 |
160 | # in an Author class (where Author has_many Books) |
d2113a68 |
161 | My::DBIC::Schema::Author->has_many(books => 'My::DBIC::Schema::Book', 'author'); |
2535b501 |
162 | |
c99393ff |
163 | my $booklist = $obj->books; |
bc0c9800 |
164 | my $booklist = $obj->books({ |
165 | name => { LIKE => '%macaroni%' }, |
166 | { prefetch => [qw/book/], |
167 | }); |
c99393ff |
168 | my @book_objs = $obj->books; |
5b89a768 |
169 | my $books_rs = $obj->books; |
170 | ( $books_rs ) = $obj->books_rs; |
503536d5 |
171 | |
c99393ff |
172 | $obj->add_to_books(\%col_data); |
503536d5 |
173 | |
2535b501 |
174 | The above C<has_many> relationship could also have been specified with an |
175 | explicit join condition: |
176 | |
177 | My::DBIC::Schema::Author->has_many( books => 'My::DBIC::Schema::Book', { |
178 | 'foreign.author' => 'self.author', |
179 | }); |
180 | |
8091aa91 |
181 | Creates a one-to-many relationship, where the corresponding elements of the |
182 | foreign class store the calling class's primary key in one (or more) of its |
183 | columns. You should pass the name of the column in the foreign class as the |
b8810cc5 |
184 | C<$cond> argument, or specify a complete join condition. |
8091aa91 |
185 | |
60a8fb95 |
186 | Three methods are created when you create a has_many relationship. The first |
2f3105ce |
187 | method is the expected accessor method, C<$accessor_name()>. The second is |
188 | almost exactly the same as the accessor method but "_rs" is added to the end of |
189 | the method name. This method works just like the normal accessor, except that |
190 | it returns a resultset no matter what, even in list context. The third method, |
2535b501 |
191 | named C<< add_to_$relname >>, will also be added to your Row items; this |
2f3105ce |
192 | allows you to insert new related items, using the same mechanism as in |
5b89a768 |
193 | L<DBIx::Class::Relationship::Base/"create_related">. |
d2113a68 |
194 | |
8091aa91 |
195 | If you delete an object in a class with a C<has_many> relationship, all |
b8810cc5 |
196 | the related objects will be deleted as well. To turn this behaviour off, |
197 | pass C<< cascade_delete => 0 >> in the C<$attr> hashref. However, any |
198 | database-level cascade or restrict will take precedence over a |
199 | DBIx-Class-based cascading delete. |
503536d5 |
200 | |
2535b501 |
201 | See L<DBIx::Class::Relationship::Base> for documentation on relationship methods. |
202 | |
bfab575a |
203 | =head2 might_have |
503536d5 |
204 | |
2f3105ce |
205 | =over 4 |
206 | |
207 | =item Arguments: $accessor_name, $related_class, $join_condition?, $attr? |
208 | |
209 | =back |
210 | |
75d07914 |
211 | My::DBIC::Schema::Author->might_have(pseudonym => |
2f3105ce |
212 | 'My::DBIC::Schema::Pseudonym'); |
213 | |
880a1a0c |
214 | my $pname = $obj->pseudonym; # to get the Pseudonym object |
8091aa91 |
215 | |
2f3105ce |
216 | Creates an optional one-to-one relationship with a class. This relationship |
2535b501 |
217 | defaults to using C<$accessor_name> as the foreign key in C<$related_class> |
2f3105ce |
218 | to resolve the join, unless C<$join_condition> specifies a column in |
219 | C<$related_class> or a join condition hash reference. |
503536d5 |
220 | |
c99393ff |
221 | If you update or delete an object in a class with a C<might_have> |
b8810cc5 |
222 | relationship, the related object will be updated or deleted as well. To |
223 | turn off this behavior, add C<< cascade_delete => 0 >> to the C<$attr> |
224 | hashref. Any database-level update or delete constraints will override |
225 | this behavior. |
503536d5 |
226 | |
2535b501 |
227 | See L<DBIx::Class::Relationship::Base> for more information. |
2f3105ce |
228 | |
bfab575a |
229 | =head2 has_one |
230 | |
2f3105ce |
231 | =over 4 |
232 | |
233 | =item Arguments: $accessor_name, $related_class_name, $join_condition?, $attr? |
234 | |
235 | =back |
236 | |
d2113a68 |
237 | My::DBIC::Schema::Book->has_one(isbn => 'My::DBIC::Schema::ISBN'); |
2f3105ce |
238 | |
239 | my $isbn_obj = $obj->isbn; # to get the ISBN object |
bfab575a |
240 | |
c99393ff |
241 | Creates a one-to-one relationship with another class. This is just like |
242 | C<might_have>, except the implication is that the other object is always |
243 | present. The only difference between C<has_one> and C<might_have> is that |
244 | C<has_one> uses an (ordinary) inner join, whereas C<might_have> uses a |
245 | left join. |
503536d5 |
246 | |
2f3105ce |
247 | The has_one relationship should be used when a row in the table has exactly one |
248 | related row in another table. If the related row might not exist in the foreign |
249 | table, use the L<DBIx::Class::Relationship/might_have> relationship. |
250 | |
251 | In the above example, each Book in the database is associated with exactly one |
252 | ISBN object. |
7411204b |
253 | |
2535b501 |
254 | See L<DBIx::Class::Relationship::Base> for documentation on relationship methods. |
87c4e602 |
255 | |
2535b501 |
256 | =head2 many_to_many |
2f3105ce |
257 | |
258 | =over 4 |
259 | |
2535b501 |
260 | =item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name, $attr? |
303cf522 |
261 | |
2f3105ce |
262 | =back |
263 | |
264 | To create a many_to_many relationship from Actor to Role: |
265 | |
75d07914 |
266 | My::DBIC::Schema::Actor->has_many( actor_roles => |
d2113a68 |
267 | 'My::DBIC::Schema::ActorRoles', |
268 | 'actor' ); |
75d07914 |
269 | My::DBIC::Schema::ActorRoles->belongs_to( role => |
d2113a68 |
270 | 'My::DBIC::Schema::Role' ); |
75d07914 |
271 | My::DBIC::Schema::ActorRoles->belongs_to( actor => |
d2113a68 |
272 | 'My::DBIC::Schema::Actor' ); |
273 | |
274 | My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles', |
71d5ed18 |
275 | 'role' ); |
bc0c9800 |
276 | |
2f3105ce |
277 | And, for the reverse relationship, from Role to Actor: |
278 | |
279 | My::DBIC::Schema::Role->has_many( actor_roles => |
280 | 'My::DBIC::Schema::ActorRoles', |
281 | 'role' ); |
282 | |
283 | My::DBIC::Schema::Role->many_to_many( actors => 'actor_roles', 'actor' ); |
284 | |
b8810cc5 |
285 | Creates accessors bridging two relationships; not strictly a relationship in |
303cf522 |
286 | its own right, although the accessor will return a resultset or collection of |
287 | objects just as a has_many would. |
b8eca5ce |
288 | |
2535b501 |
289 | In the above example, ActorRoles is the link table class, and Role is the |
290 | foreign class. The C<$link_rel_name> parameter is the name of the accessor for |
291 | the has_many relationship from this table to the link table, and the |
292 | C<$foreign_rel_name> parameter is the accessor for the belongs_to relationship |
293 | from the link table to the foreign table. |
294 | |
d2113a68 |
295 | To use many_to_many, existing relationships from the original table to the link |
75d07914 |
296 | table, and from the link table to the end table must already exist, these |
d2113a68 |
297 | relation names are then used in the many_to_many call. |
7411204b |
298 | |
2535b501 |
299 | In the above example, the Actor class will have 3 many_to_many accessor methods |
2f3105ce |
300 | set: C<$roles>, C<$add_to_roles>, C<$set_roles>, and similarly named accessors |
2535b501 |
301 | will be created for the Role class for the C<actors> many_to_many |
302 | relationship. |
303 | |
304 | See L<DBIx::Class::Relationship::Base> for documentation on relationship methods. |
2f3105ce |
305 | |
34d52be2 |
306 | =cut |
307 | |
b8e1e21f |
308 | 1; |
34d52be2 |
309 | |
34d52be2 |
310 | =head1 AUTHORS |
311 | |
daec44b8 |
312 | Matt S. Trout <mst@shadowcatsystems.co.uk> |
34d52be2 |
313 | |
314 | =head1 LICENSE |
315 | |
316 | You may distribute this code under the same terms as Perl itself. |
317 | |
318 | =cut |
319 | |