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