1 package DBIx::Class::Relationship;
6 use base qw/DBIx::Class/;
8 __PACKAGE__->load_own_components(qw/
18 DBIx::Class::Relationship - Inter-table relationships
22 MyDB::Schema::Actor->has_many('actorroles' => 'MyDB::Schema::ActorRole',
24 MyDB::Schema::Role->has_many('actorroles' => 'MyDB::Schema::ActorRole',
26 MyDB::Schema::ActorRole->belongs_to('role' => 'MyDB::Schema::Role');
27 MyDB::Schema::ActorRole->belongs_to('actor' => 'MyDB::Schema::Actor');
29 MyDB::Schema::Role->many_to_many('actors' => 'actorroles', 'actor');
30 MyDB::Schema::Actor->many_to_many('roles' => 'actorroles', 'role');
32 $schema->resultset('Actor')->roles();
33 $schema->resultset('Role')->search_related('actors', { Name => 'Fred' });
34 $schema->resultset('ActorRole')->add_to_roles({ Name => 'Sherlock Holmes'});
36 See L<DBIx::Class::Manual::Cookbook> for more.
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:
55 1 | 1 | Rulers of the universe
56 2 | 1 | Rulers of the galaxy
58 Then without relationships, the method of getting all books by Fred goes like
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:
66 my $fredsbooks = $schema->resultset('Author')->find({ Name => 'Fred' })->books;
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.
78 my $cheapfredbooks = $schema->resultset('Author')->find({
80 })->books->search_related('prices', {
81 Price => { '<=' => '5.00' },
84 will produce a query something like:
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
91 all without needing multiple fetches.
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>.
100 All helper methods take the following arguments:
102 __PACKAGE__>$method_name('relname', 'Foreign::Class', $cond, $attrs);
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 See L<DBIx::Class::Relationship::Base> for a list of valid attributes.
112 =item Arguments: $accessor_name, $related_class, $foreign_key_column?, $attr?
116 # in a Book class (where Author has many Books)
117 My::DBIC::Schema::Book->belongs_to(author => 'My::DBIC::Schema::Author');
118 my $author_obj = $obj->author;
119 $obj->author($new_author_obj);
121 Creates a relationship where the calling class stores the foreign class's
122 primary key in one (or more) of its columns. If C<$cond> is a column name
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.
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:
134 # in a Book class (where Author has_many Books)
135 __PACKAGE__->belongs_to(author => 'My::DBIC::Schema::Author',
136 'author', {join_type => 'left'});
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.
143 NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent
150 =item Arguments: $accessor_name, $related_class, $foreign_key_column?, $attr?
154 # in an Author class (where Author has_many Books)
155 My::DBIC::Schema::Author->has_many(books => 'My::DBIC::Schema::Book', 'author');
156 my $booklist = $obj->books;
157 my $booklist = $obj->books({
158 name => { LIKE => '%macaroni%' },
159 { prefetch => [qw/book/],
161 my @book_objs = $obj->books;
162 my $books_rs = $obj->books;
163 ( $books_rs ) = $obj->books_rs;
165 $obj->add_to_books(\%col_data);
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
170 C<$cond> argument, or specify a complete join condition.
172 Three methods are created when you create a has_many relationship. The first
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
179 L<DBIx::Class::Relationship::Base/"create_related">.
181 If you delete an object in a class with a C<has_many> relationship, all
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.
191 =item Arguments: $accessor_name, $related_class, $join_condition?, $attr?
195 My::DBIC::Schema::Author->might_have(pseudonym =>
196 'My::DBIC::Schema::Pseudonym');
198 my $pname = $obj->pseudonym; # to get the Pseudonym object
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.
205 If you update or delete an object in a class with a C<might_have>
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
217 =item Arguments: $accessor_name, $related_class_name, $join_condition?, $attr?
221 My::DBIC::Schema::Book->has_one(isbn => 'My::DBIC::Schema::ISBN');
223 my $isbn_obj = $obj->isbn; # to get the ISBN object
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
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.
235 In the above example, each Book in the database is associated with exactly one
246 =item C<$accessor_name>: The name of the new many_to_many accessor,
248 =item C<$link_rel_name>: The accessor name of the has_many relationship from
249 the current table to the link table,
251 =item C<$foreign_rel_name>: The accessor name for the belongs_to relationship
252 from the link table to the foreign table
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>.
261 To create a many_to_many relationship from Actor to Role:
263 My::DBIC::Schema::Actor->has_many( actor_roles =>
264 'My::DBIC::Schema::ActorRoles',
266 My::DBIC::Schema::ActorRoles->belongs_to( role =>
267 'My::DBIC::Schema::Role' );
268 My::DBIC::Schema::ActorRoles->belongs_to( actor =>
269 'My::DBIC::Schema::Actor' );
271 My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles',
274 And, for the reverse relationship, from Role to Actor:
276 My::DBIC::Schema::Role->has_many( actor_roles =>
277 'My::DBIC::Schema::ActorRoles',
280 My::DBIC::Schema::Role->many_to_many( actors => 'actor_roles', 'actor' );
282 Creates accessors bridging two relationships; not strictly a relationship in
283 its own right, although the accessor will return a resultset or collection of
284 objects just as a has_many would.
286 To use many_to_many, existing relationships from the original table to the link
287 table, and from the link table to the end table must already exist, these
288 relation names are then used in the many_to_many call.
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
301 Matt S. Trout <mst@shadowcatsystems.co.uk>
305 You may distribute this code under the same terms as Perl itself.