1 package DBIx::Class::Relationship::Base;
7 use base qw/DBIx::Class/;
11 DBIx::Class::Relationship::Base - Inter-table relationships
17 This class provides methods to describe the relationships between the
18 tables in your database model. These are the "bare bones" relationships
19 methods, for predefined ones, look in L<DBIx::Class::Relationship>.
23 =head2 add_relationship
27 =item Arguments: 'relname', 'Foreign::Class', $cond, $attrs
31 __PACKAGE__->add_relationship('relname', 'Foreign::Class', $cond, $attrs);
35 The condition needs to be an L<SQL::Abstract>-style representation of the
36 join between the tables. When resolving the condition for use in a C<JOIN>,
37 keys using the pseudo-table C<foreign> are resolved to mean "the Table on the
38 other side of the relationship", and values using the pseudo-table C<self>
39 are resolved to mean "the Table this class is representing". Other
40 restrictions, such as by value, sub-select and other tables, may also be
41 used. Please check your database for C<JOIN> parameter support.
43 For example, if you're creating a relationship from C<Author> to C<Book>, where
44 the C<Book> table has a column C<author_id> containing the ID of the C<Author>
47 { 'foreign.author_id' => 'self.id' }
49 will result in the C<JOIN> clause
51 author me JOIN book book ON book.author_id = me.id
53 For multi-column foreign keys, you will need to specify a C<foreign>-to-C<self>
54 mapping for each column in the key. For example, if you're creating a
55 relationship from C<Book> to C<Edition>, where the C<Edition> table refers to a
56 publisher and a type (e.g. "paperback"):
59 'foreign.publisher_id' => 'self.publisher_id',
60 'foreign.type_id' => 'self.type_id',
63 This will result in the C<JOIN> clause:
65 book me JOIN edition edition ON edition.publisher_id = me.publisher_id
66 AND edition.type_id = me.type_id
68 Each key-value pair provided in a hashref will be used as C<AND>ed conditions.
69 To add an C<OR>ed condition, use an arrayref of hashrefs. See the
70 L<SQL::Abstract> documentation for more details.
74 The L<standard ResultSet attributes|DBIx::Class::ResultSet/ATTRIBUTES> may
75 be used as relationship attributes. In particular, the 'where' attribute is
76 useful for filtering relationships:
78 __PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User',
79 { 'foreign.user_id' => 'self.user_id' },
80 { where => { valid => 1 } }
83 The following attributes are also valid:
89 Explicitly specifies the type of join to use in the relationship. Any SQL
90 join type is valid, e.g. C<LEFT> or C<RIGHT>. It will be placed in the SQL
91 command immediately before C<JOIN>.
95 An arrayref containing a list of accessors in the foreign class to create in
96 the main class. If, for example, you do the following:
98 MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes',
100 proxy => [ qw/notes/ ],
103 Then, assuming MyDB::Schema::LinerNotes has an accessor named notes, you can do:
105 my $cd = MyDB::Schema::CD->find(1);
106 $cd->notes('Notes go here'); # set notes -- LinerNotes object is
107 # created if it doesn't exist
111 Specifies the type of accessor that should be created for the relationship.
112 Valid values are C<single> (for when there is only a single related object),
113 C<multi> (when there can be many), and C<filter> (for when there is a single
114 related object, but you also want the relationship accessor to double as
115 a column accessor). For C<multi> accessors, an add_to_* method is also
116 created, which calls C<create_related> for the relationship.
118 =item is_foreign_key_constraint
120 If you are using L<SQL::Translator> to create SQL for you and you find that it
121 is creating constraints where it shouldn't, or not creating them where it
122 should, set this attribute to a true or false value to override the detection
123 of when to create constraints.
127 If C<cascade_copy> is true on a C<has_many> relationship for an
128 object, then when you copy the object all the related objects will
129 be copied too. To turn this behaviour off, pass C<< cascade_copy => 0 >>
130 in the C<$attr> hashref. The behaviour defaults to C<< cascade_copy => 1 >>.
134 By default, DBIx::Class cascades deletes across C<has_many> and
135 C<might_have> relationships. You can disable this behaviour on a
136 per-relationship basis by supplying C<< cascade_delete => 0 >> in the
137 relationship attributes.
139 The cascaded operations are performed after the requested delete,
140 so if your database has a constraint on the relationship, it will
141 have deleted/updated the related records or raised an exception
142 before DBIx::Class gets to perform the cascaded operation.
146 By default, DBIx::Class cascades updates across C<has_many> and
147 C<might_have> relationships. You can disable this behaviour on a
148 per-relationship basis by supplying C<< cascade_update => 0 >> in the
149 relationship attributes.
151 The cascaded operations are performed after the requested update,
152 so if your database has a constraint on the relationship, it will
153 have updated/updated the related records or raised an exception
154 before DBIx::Class gets to perform the cascaded operation.
156 =item on_delete / on_update
158 If you are using L<SQL::Translator> to create SQL for you, you can use these
159 attributes to explicitly set the desired C<ON DELETE> or C<ON UPDATE> constraint
160 type. If not supplied the SQLT parser will attempt to infer the constraint type by
161 interrogating the attributes of the B<opposite> relationship. For any 'multi'
162 relationship with C<< cascade_delete => 1 >>, the corresponding belongs_to
163 relationship will be created with an C<ON DELETE CASCADE> constraint. For any
164 relationship bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint
165 will be C<ON UPDATE CASCADE>. If you wish to disable this autodetection, and just
166 use the RDBMS' default constraint type, pass C<< on_delete => undef >> or
167 C<< on_delete => '' >>, and the same for C<on_update> respectively.
171 Tells L<SQL::Translator> that the foreign key constraint it creates should be
172 deferrable. In other words, the user may request that the constraint be ignored
173 until the end of the transaction. Currently, only the PostgreSQL producer
174 actually supports this.
178 Tells L<SQL::Translator> to add an index for this constraint. Can also be
179 specified globally in the args to L<DBIx::Class::Schema/deploy> or
180 L<DBIx::Class::Schema/create_ddl_dir>. Default is on, set to 0 to disable.
184 =head2 register_relationship
188 =item Arguments: $relname, $rel_info
192 Registers a relationship on the class. This is called internally by
193 DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
197 sub register_relationship { }
199 =head2 related_resultset
203 =item Arguments: $relationship_name
205 =item Return Value: $related_resultset
209 $rs = $cd->related_resultset('artist');
211 Returns a L<DBIx::Class::ResultSet> for the relationship named
216 sub related_resultset {
218 $self->throw_exception("Can't call *_related as class methods")
221 my $rel_info = $self->relationship_info($rel);
222 $self->throw_exception( "No such relationship ${rel}" )
225 return $self->{related_resultsets}{$rel} ||= do {
226 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
227 $attrs = { %{$rel_info->{attrs} || {}}, %$attrs };
229 $self->throw_exception( "Invalid query: @_" )
230 if (@_ > 1 && (@_ % 2 == 1));
231 my $query = ((@_ > 1) ? {@_} : shift);
233 my $source = $self->result_source;
235 # condition resolution may fail if an incomplete master-object prefetch
236 # is encountered - that is ok during prefetch construction (not yet in_storage)
237 my $cond = eval { $source->_resolve_condition( $rel_info->{cond}, $rel, $self ) };
239 if ($self->in_storage) {
240 $self->throw_exception ($err);
243 $cond = $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION;
247 if ($cond eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) {
248 my $reverse = $source->reverse_relationship_info($rel);
249 foreach my $rev_rel (keys %$reverse) {
250 if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') {
251 $attrs->{related_objects}{$rev_rel} = [ $self ];
252 Scalar::Util::weaken($attrs->{related_object}{$rev_rel}[0]);
254 $attrs->{related_objects}{$rev_rel} = $self;
255 Scalar::Util::weaken($attrs->{related_object}{$rev_rel});
259 if (ref $cond eq 'ARRAY') {
261 if (ref $_ eq 'HASH') {
263 foreach my $key (keys %$_) {
264 my $newkey = $key !~ /\./ ? "me.$key" : $key;
265 $hash->{$newkey} = $_->{$key};
272 } elsif (ref $cond eq 'HASH') {
273 foreach my $key (grep { ! /\./ } keys %$cond) {
274 $cond->{"me.$key"} = delete $cond->{$key};
277 $query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
278 $self->result_source->related_source($rel)->resultset->search(
284 =head2 search_related
286 @objects = $rs->search_related('relname', $cond, $attrs);
287 $objects_rs = $rs->search_related('relname', $cond, $attrs);
289 Run a search on a related resultset. The search will be restricted to the
290 item or items represented by the L<DBIx::Class::ResultSet> it was called
291 upon. This method can be called on a ResultSet, a Row or a ResultSource class.
296 return shift->related_resultset(shift)->search(@_);
299 =head2 search_related_rs
301 ( $objects_rs ) = $rs->search_related_rs('relname', $cond, $attrs);
303 This method works exactly the same as search_related, except that
304 it guarantees a resultset, even in list context.
308 sub search_related_rs {
309 return shift->related_resultset(shift)->search_rs(@_);
314 $obj->count_related('relname', $cond, $attrs);
316 Returns the count of all the items in the related resultset, restricted by the
317 current item or where conditions. Can be called on a
318 L<DBIx::Class::Manual::Glossary/"ResultSet"> or a
319 L<DBIx::Class::Manual::Glossary/"Row"> object.
325 return $self->search_related(@_)->count;
330 my $new_obj = $obj->new_related('relname', \%col_data);
332 Create a new item of the related foreign class. If called on a
333 L<Row|DBIx::Class::Manual::Glossary/"Row"> object, it will magically
334 set any foreign key columns of the new object to the related primary
335 key columns of the source object for you. The newly created item will
336 not be saved into your storage until you call L<DBIx::Class::Row/insert>
342 my ($self, $rel, $values, $attrs) = @_;
343 return $self->search_related($rel)->new($values, $attrs);
346 =head2 create_related
348 my $new_obj = $obj->create_related('relname', \%col_data);
350 Creates a new item, similarly to new_related, and also inserts the item's data
351 into your storage medium. See the distinction between C<create> and C<new>
352 in L<DBIx::Class::ResultSet> for details.
359 my $obj = $self->search_related($rel)->create(@_);
360 delete $self->{related_resultsets}->{$rel};
366 my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals);
368 Attempt to find a related object using its primary key or unique constraints.
369 See L<DBIx::Class::ResultSet/find> for details.
376 return $self->search_related($rel)->find(@_);
379 =head2 find_or_new_related
381 my $new_obj = $obj->find_or_new_related('relname', \%col_data);
383 Find an item of a related class. If none exists, instantiate a new item of the
384 related class. The object will not be saved into your storage until you call
385 L<DBIx::Class::Row/insert> on it.
389 sub find_or_new_related {
391 my $obj = $self->find_related(@_);
392 return defined $obj ? $obj : $self->new_related(@_);
395 =head2 find_or_create_related
397 my $new_obj = $obj->find_or_create_related('relname', \%col_data);
399 Find or create an item of a related class. See
400 L<DBIx::Class::ResultSet/find_or_create> for details.
404 sub find_or_create_related {
406 my $obj = $self->find_related(@_);
407 return (defined($obj) ? $obj : $self->create_related(@_));
410 =head2 update_or_create_related
412 my $updated_item = $obj->update_or_create_related('relname', \%col_data, \%attrs?);
414 Update or create an item of a related class. See
415 L<DBIx::Class::ResultSet/update_or_create> for details.
419 sub update_or_create_related {
422 return $self->related_resultset($rel)->update_or_create(@_);
425 =head2 set_from_related
427 $book->set_from_related('author', $author_obj);
428 $book->author($author_obj); ## same thing
430 Set column values on the current object, using related values from the given
431 related object. This is used to associate previously separate objects, for
432 example, to set the correct author for a book, find the Author object, then
433 call set_from_related on the book.
435 This is called internally when you pass existing objects as values to
436 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
438 The columns are only set in the local copy of the object, call L</update> to
439 set them in the storage.
443 sub set_from_related {
444 my ($self, $rel, $f_obj) = @_;
445 my $rel_info = $self->relationship_info($rel);
446 $self->throw_exception( "No such relationship ${rel}" ) unless $rel_info;
447 my $cond = $rel_info->{cond};
448 $self->throw_exception(
449 "set_from_related can only handle a hash condition; the ".
450 "condition for $rel is of type ".
451 (ref $cond ? ref $cond : 'plain scalar')
452 ) unless ref $cond eq 'HASH';
453 if (defined $f_obj) {
454 my $f_class = $rel_info->{class};
455 $self->throw_exception( "Object $f_obj isn't a ".$f_class )
456 unless Scalar::Util::blessed($f_obj) and $f_obj->isa($f_class);
459 $self->result_source->_resolve_condition(
460 $rel_info->{cond}, $f_obj, $rel));
464 =head2 update_from_related
466 $book->update_from_related('author', $author_obj);
468 The same as L</"set_from_related">, but the changes are immediately updated
473 sub update_from_related {
475 $self->set_from_related(@_);
479 =head2 delete_related
481 $obj->delete_related('relname', $cond, $attrs);
483 Delete any related item subject to the given conditions.
489 my $obj = $self->search_related(@_)->delete;
490 delete $self->{related_resultsets}->{$_[0]};
496 B<Currently only available for C<has_many>, C<many-to-many> and 'multi' type
501 =item Arguments: ($foreign_vals | $obj), $link_vals?
505 my $role = $schema->resultset('Role')->find(1);
506 $actor->add_to_roles($role);
507 # creates a My::DBIC::Schema::ActorRoles linking table row object
509 $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
510 # creates a new My::DBIC::Schema::Role row object and the linking table
511 # object with an extra column in the link
513 Adds a linking table object for C<$obj> or C<$foreign_vals>. If the first
514 argument is a hash reference, the related object is created first with the
515 column values in the hash. If an object reference is given, just the linking
516 table object is created. In either case, any additional column values for the
517 linking table object can be specified in C<$link_vals>.
521 B<Currently only available for C<many-to-many> relationships.>
525 =item Arguments: (\@hashrefs | \@objs), $link_vals?
529 my $actor = $schema->resultset('Actor')->find(1);
530 my @roles = $schema->resultset('Role')->search({ role =>
531 { '-in' => ['Fred', 'Barney'] } } );
533 $actor->set_roles(\@roles);
534 # Replaces all of $actor's previous roles with the two named
536 $actor->set_roles(\@roles, { salary => 15_000_000 });
537 # Sets a column in the link table for all roles
540 Replace all the related objects with the given reference to a list of
541 objects. This does a C<delete> B<on the link table resultset> to remove the
542 association between the current object and all related objects, then calls
543 C<add_to_$rel> repeatedly to link all the new objects.
545 Note that this means that this method will B<not> delete any objects in the
546 table on the right side of the relation, merely that it will delete the link
549 Due to a mistake in the original implementation of this method, it will also
550 accept a list of objects or hash references. This is B<deprecated> and will be
551 removed in a future version.
553 =head2 remove_from_$rel
555 B<Currently only available for C<many-to-many> relationships.>
559 =item Arguments: $obj
563 my $role = $schema->resultset('Role')->find(1);
564 $actor->remove_from_roles($role);
565 # removes $role's My::DBIC::Schema::ActorRoles linking table row object
567 Removes the link between the current object and the related object. Note that
568 the related object itself won't be deleted unless you call ->delete() on
569 it. This method just removes the link between the two objects.
573 Matt S. Trout <mst@shadowcatsystems.co.uk>
577 You may distribute this code under the same terms as Perl itself.