1 package DBIx::Class::Relationship::Base;
6 use base qw/DBIx::Class/;
8 use Scalar::Util qw/weaken blessed/;
14 DBIx::Class::Relationship::Base - Inter-table relationships
20 This class provides methods to describe the relationships between the
21 tables in your database model. These are the "bare bones" relationships
22 methods, for predefined ones, look in L<DBIx::Class::Relationship>.
26 =head2 add_relationship
30 =item Arguments: 'relname', 'Foreign::Class', $cond, $attrs
34 __PACKAGE__->add_relationship('relname', 'Foreign::Class', $cond, $attrs);
38 The condition needs to be an L<SQL::Abstract>-style representation of the
39 join between the tables. When resolving the condition for use in a C<JOIN>,
40 keys using the pseudo-table C<foreign> are resolved to mean "the Table on the
41 other side of the relationship", and values using the pseudo-table C<self>
42 are resolved to mean "the Table this class is representing". Other
43 restrictions, such as by value, sub-select and other tables, may also be
44 used. Please check your database for C<JOIN> parameter support.
46 For example, if you're creating a relationship from C<Author> to C<Book>, where
47 the C<Book> table has a column C<author_id> containing the ID of the C<Author>
50 { 'foreign.author_id' => 'self.id' }
52 will result in the C<JOIN> clause
54 author me JOIN book book ON book.author_id = me.id
56 For multi-column foreign keys, you will need to specify a C<foreign>-to-C<self>
57 mapping for each column in the key. For example, if you're creating a
58 relationship from C<Book> to C<Edition>, where the C<Edition> table refers to a
59 publisher and a type (e.g. "paperback"):
62 'foreign.publisher_id' => 'self.publisher_id',
63 'foreign.type_id' => 'self.type_id',
66 This will result in the C<JOIN> clause:
68 book me JOIN edition edition ON edition.publisher_id = me.publisher_id
69 AND edition.type_id = me.type_id
71 Each key-value pair provided in a hashref will be used as C<AND>ed conditions.
72 To add an C<OR>ed condition, use an arrayref of hashrefs. See the
73 L<SQL::Abstract> documentation for more details.
77 The L<standard ResultSet attributes|DBIx::Class::ResultSet/ATTRIBUTES> may
78 be used as relationship attributes. In particular, the 'where' attribute is
79 useful for filtering relationships:
81 __PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User',
82 { 'foreign.user_id' => 'self.user_id' },
83 { where => { valid => 1 } }
86 The following attributes are also valid:
92 Explicitly specifies the type of join to use in the relationship. Any SQL
93 join type is valid, e.g. C<LEFT> or C<RIGHT>. It will be placed in the SQL
94 command immediately before C<JOIN>.
96 =item proxy =E<gt> $column | \@columns | \%column
102 An arrayref containing a list of accessors in the foreign class to create in
103 the main class. If, for example, you do the following:
105 MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes',
107 proxy => [ qw/notes/ ],
110 Then, assuming MyDB::Schema::LinerNotes has an accessor named notes, you can do:
112 my $cd = MyDB::Schema::CD->find(1);
113 $cd->notes('Notes go here'); # set notes -- LinerNotes object is
114 # created if it doesn't exist
118 A hashref where each key is the accessor you want installed in the main class,
119 and its value is the name of the original in the fireign class.
121 MyDB::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd', {
122 proxy => { cd_title => 'title' },
125 This will create an accessor named C<cd_title> on the C<$track> row object.
129 NOTE: you can pass a nested struct too, for example:
131 MyDB::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd', {
132 proxy => [ 'year', { cd_title => 'title' } ],
137 Specifies the type of accessor that should be created for the relationship.
138 Valid values are C<single> (for when there is only a single related object),
139 C<multi> (when there can be many), and C<filter> (for when there is a single
140 related object, but you also want the relationship accessor to double as
141 a column accessor). For C<multi> accessors, an add_to_* method is also
142 created, which calls C<create_related> for the relationship.
144 =item is_foreign_key_constraint
146 If you are using L<SQL::Translator> to create SQL for you and you find that it
147 is creating constraints where it shouldn't, or not creating them where it
148 should, set this attribute to a true or false value to override the detection
149 of when to create constraints.
153 If C<cascade_copy> is true on a C<has_many> relationship for an
154 object, then when you copy the object all the related objects will
155 be copied too. To turn this behaviour off, pass C<< cascade_copy => 0 >>
156 in the C<$attr> hashref.
158 The behaviour defaults to C<< cascade_copy => 1 >> for C<has_many>
163 By default, DBIx::Class cascades deletes across C<has_many>,
164 C<has_one> and C<might_have> relationships. You can disable this
165 behaviour on a per-relationship basis by supplying
166 C<< cascade_delete => 0 >> in the relationship attributes.
168 The cascaded operations are performed after the requested delete,
169 so if your database has a constraint on the relationship, it will
170 have deleted/updated the related records or raised an exception
171 before DBIx::Class gets to perform the cascaded operation.
175 By default, DBIx::Class cascades updates across C<has_one> and
176 C<might_have> relationships. You can disable this behaviour on a
177 per-relationship basis by supplying C<< cascade_update => 0 >> in
178 the relationship attributes.
180 This is not a RDMS style cascade update - it purely means that when
181 an object has update called on it, all the related objects also
182 have update called. It will not change foreign keys automatically -
183 you must arrange to do this yourself.
185 =item on_delete / on_update
187 If you are using L<SQL::Translator> to create SQL for you, you can use these
188 attributes to explicitly set the desired C<ON DELETE> or C<ON UPDATE> constraint
189 type. If not supplied the SQLT parser will attempt to infer the constraint type by
190 interrogating the attributes of the B<opposite> relationship. For any 'multi'
191 relationship with C<< cascade_delete => 1 >>, the corresponding belongs_to
192 relationship will be created with an C<ON DELETE CASCADE> constraint. For any
193 relationship bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint
194 will be C<ON UPDATE CASCADE>. If you wish to disable this autodetection, and just
195 use the RDBMS' default constraint type, pass C<< on_delete => undef >> or
196 C<< on_delete => '' >>, and the same for C<on_update> respectively.
200 Tells L<SQL::Translator> that the foreign key constraint it creates should be
201 deferrable. In other words, the user may request that the constraint be ignored
202 until the end of the transaction. Currently, only the PostgreSQL producer
203 actually supports this.
207 Tells L<SQL::Translator> to add an index for this constraint. Can also be
208 specified globally in the args to L<DBIx::Class::Schema/deploy> or
209 L<DBIx::Class::Schema/create_ddl_dir>. Default is on, set to 0 to disable.
213 =head2 register_relationship
217 =item Arguments: $relname, $rel_info
221 Registers a relationship on the class. This is called internally by
222 DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
226 sub register_relationship { }
228 =head2 related_resultset
232 =item Arguments: $relationship_name
234 =item Return Value: $related_resultset
238 $rs = $cd->related_resultset('artist');
240 Returns a L<DBIx::Class::ResultSet> for the relationship named
245 sub related_resultset {
247 $self->throw_exception("Can't call *_related as class methods")
250 my $rel_info = $self->relationship_info($rel);
251 $self->throw_exception( "No such relationship ${rel}" )
254 return $self->{related_resultsets}{$rel} ||= do {
255 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
256 $attrs = { %{$rel_info->{attrs} || {}}, %$attrs };
258 $self->throw_exception( "Invalid query: @_" )
259 if (@_ > 1 && (@_ % 2 == 1));
260 my $query = ((@_ > 1) ? {@_} : shift);
262 my $source = $self->result_source;
264 # condition resolution may fail if an incomplete master-object prefetch
265 # is encountered - that is ok during prefetch construction (not yet in_storage)
267 # if $rel_info->{cond} is a CODE, we might need to join from the
268 # current resultsource instead of just querying the target
269 # resultsource, in that case, the condition might provide an
270 # additional condition in order to avoid an unecessary join if
271 # that is at all possible.
272 my ($cond, $extended_cond) = try {
273 $source->_resolve_condition( $rel_info->{cond}, $rel, $self )
276 if ($self->in_storage) {
277 $self->throw_exception ($_);
280 $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION; # RV
283 if ($cond eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) {
284 my $reverse = $source->reverse_relationship_info($rel);
285 foreach my $rev_rel (keys %$reverse) {
286 if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') {
287 $attrs->{related_objects}{$rev_rel} = [ $self ];
288 weaken $attrs->{related_object}{$rev_rel}[0];
290 $attrs->{related_objects}{$rev_rel} = $self;
291 weaken $attrs->{related_object}{$rev_rel};
296 # this is where we're going to check if we have an extended
297 # rel. In that case, we need to: 1) If there's a second
298 # condition, we use that instead. 2) If there is only one
299 # condition, we need to join the current resultsource and have
300 # additional conditions.
301 if (ref $rel_info->{cond} eq 'CODE') {
302 # this is an extended relationship.
303 if ($extended_cond) {
304 $cond = $extended_cond;
308 # it's a bit hard to find out what to do with other joins
309 $self->throw_exception('Extended relationship '.$rel.' with additional join requires optimized declaration')
310 if exists $attrs->{join} && $attrs->{join};
312 # aliases get a bit more complicated, so we won't accept additional queries
313 $self->throw_exception('Extended relationship '.$rel.' with additional query requires optimized declaration')
317 [ { $rel => $self->result_source->from },
318 [ { 'me' => $self->result_source->related_source($rel)->from }, { 1 => 1 } ] ];
320 $cond->{"${rel}.${_}"} = $self->get_column($_) for $self->result_source->primary_columns;
324 if (ref $cond eq 'ARRAY') {
326 if (ref $_ eq 'HASH') {
328 foreach my $key (keys %$_) {
329 my $newkey = $key !~ /\./ ? "me.$key" : $key;
330 $hash->{$newkey} = $_->{$key};
337 } elsif (ref $cond eq 'HASH') {
338 foreach my $key (grep { ! /\./ } keys %$cond) {
339 $cond->{"me.$key"} = delete $cond->{$key};
343 $query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
344 $self->result_source->related_source($rel)->resultset->search(
350 =head2 search_related
352 @objects = $rs->search_related('relname', $cond, $attrs);
353 $objects_rs = $rs->search_related('relname', $cond, $attrs);
355 Run a search on a related resultset. The search will be restricted to the
356 item or items represented by the L<DBIx::Class::ResultSet> it was called
357 upon. This method can be called on a ResultSet, a Row or a ResultSource class.
362 return shift->related_resultset(shift)->search(@_);
365 =head2 search_related_rs
367 ( $objects_rs ) = $rs->search_related_rs('relname', $cond, $attrs);
369 This method works exactly the same as search_related, except that
370 it guarantees a resultset, even in list context.
374 sub search_related_rs {
375 return shift->related_resultset(shift)->search_rs(@_);
380 $obj->count_related('relname', $cond, $attrs);
382 Returns the count of all the items in the related resultset, restricted by the
383 current item or where conditions. Can be called on a
384 L<DBIx::Class::Manual::Glossary/"ResultSet"> or a
385 L<DBIx::Class::Manual::Glossary/"Row"> object.
391 return $self->search_related(@_)->count;
396 my $new_obj = $obj->new_related('relname', \%col_data);
398 Create a new item of the related foreign class. If called on a
399 L<Row|DBIx::Class::Manual::Glossary/"Row"> object, it will magically
400 set any foreign key columns of the new object to the related primary
401 key columns of the source object for you. The newly created item will
402 not be saved into your storage until you call L<DBIx::Class::Row/insert>
408 my ($self, $rel, $values, $attrs) = @_;
409 return $self->search_related($rel)->new($values, $attrs);
412 =head2 create_related
414 my $new_obj = $obj->create_related('relname', \%col_data);
416 Creates a new item, similarly to new_related, and also inserts the item's data
417 into your storage medium. See the distinction between C<create> and C<new>
418 in L<DBIx::Class::ResultSet> for details.
425 my $obj = $self->search_related($rel)->create(@_);
426 delete $self->{related_resultsets}->{$rel};
432 my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals);
434 Attempt to find a related object using its primary key or unique constraints.
435 See L<DBIx::Class::ResultSet/find> for details.
442 return $self->search_related($rel)->find(@_);
445 =head2 find_or_new_related
447 my $new_obj = $obj->find_or_new_related('relname', \%col_data);
449 Find an item of a related class. If none exists, instantiate a new item of the
450 related class. The object will not be saved into your storage until you call
451 L<DBIx::Class::Row/insert> on it.
455 sub find_or_new_related {
457 my $obj = $self->find_related(@_);
458 return defined $obj ? $obj : $self->new_related(@_);
461 =head2 find_or_create_related
463 my $new_obj = $obj->find_or_create_related('relname', \%col_data);
465 Find or create an item of a related class. See
466 L<DBIx::Class::ResultSet/find_or_create> for details.
470 sub find_or_create_related {
472 my $obj = $self->find_related(@_);
473 return (defined($obj) ? $obj : $self->create_related(@_));
476 =head2 update_or_create_related
478 my $updated_item = $obj->update_or_create_related('relname', \%col_data, \%attrs?);
480 Update or create an item of a related class. See
481 L<DBIx::Class::ResultSet/update_or_create> for details.
485 sub update_or_create_related {
488 return $self->related_resultset($rel)->update_or_create(@_);
491 =head2 set_from_related
493 $book->set_from_related('author', $author_obj);
494 $book->author($author_obj); ## same thing
496 Set column values on the current object, using related values from the given
497 related object. This is used to associate previously separate objects, for
498 example, to set the correct author for a book, find the Author object, then
499 call set_from_related on the book.
501 This is called internally when you pass existing objects as values to
502 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
504 The columns are only set in the local copy of the object, call L</update> to
505 set them in the storage.
509 sub set_from_related {
510 my ($self, $rel, $f_obj) = @_;
511 my $rel_info = $self->relationship_info($rel);
512 $self->throw_exception( "No such relationship ${rel}" ) unless $rel_info;
513 my $cond = $rel_info->{cond};
514 $self->throw_exception(
515 "set_from_related can only handle a hash condition; the ".
516 "condition for $rel is of type ".
517 (ref $cond ? ref $cond : 'plain scalar')
518 ) unless ref $cond eq 'HASH';
519 if (defined $f_obj) {
520 my $f_class = $rel_info->{class};
521 $self->throw_exception( "Object $f_obj isn't a ".$f_class )
522 unless blessed $f_obj and $f_obj->isa($f_class);
525 # _resolve_condition might return two hashrefs, specially in the
526 # current case, since we know $f_object is an object.
527 my ($condref1, $condref2) = $self->result_source->_resolve_condition
528 ($rel_info->{cond}, $f_obj, $rel);
530 # if we get two condrefs, we need to use the second, otherwise we
532 $self->set_columns($condref2 ? $condref2 : $condref1);
537 =head2 update_from_related
539 $book->update_from_related('author', $author_obj);
541 The same as L</"set_from_related">, but the changes are immediately updated
546 sub update_from_related {
548 $self->set_from_related(@_);
552 =head2 delete_related
554 $obj->delete_related('relname', $cond, $attrs);
556 Delete any related item subject to the given conditions.
562 my $obj = $self->search_related(@_)->delete;
563 delete $self->{related_resultsets}->{$_[0]};
569 B<Currently only available for C<has_many>, C<many-to-many> and 'multi' type
574 =item Arguments: ($foreign_vals | $obj), $link_vals?
578 my $role = $schema->resultset('Role')->find(1);
579 $actor->add_to_roles($role);
580 # creates a My::DBIC::Schema::ActorRoles linking table row object
582 $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
583 # creates a new My::DBIC::Schema::Role row object and the linking table
584 # object with an extra column in the link
586 Adds a linking table object for C<$obj> or C<$foreign_vals>. If the first
587 argument is a hash reference, the related object is created first with the
588 column values in the hash. If an object reference is given, just the linking
589 table object is created. In either case, any additional column values for the
590 linking table object can be specified in C<$link_vals>.
594 B<Currently only available for C<many-to-many> relationships.>
598 =item Arguments: (\@hashrefs | \@objs), $link_vals?
602 my $actor = $schema->resultset('Actor')->find(1);
603 my @roles = $schema->resultset('Role')->search({ role =>
604 { '-in' => ['Fred', 'Barney'] } } );
606 $actor->set_roles(\@roles);
607 # Replaces all of $actor's previous roles with the two named
609 $actor->set_roles(\@roles, { salary => 15_000_000 });
610 # Sets a column in the link table for all roles
613 Replace all the related objects with the given reference to a list of
614 objects. This does a C<delete> B<on the link table resultset> to remove the
615 association between the current object and all related objects, then calls
616 C<add_to_$rel> repeatedly to link all the new objects.
618 Note that this means that this method will B<not> delete any objects in the
619 table on the right side of the relation, merely that it will delete the link
622 Due to a mistake in the original implementation of this method, it will also
623 accept a list of objects or hash references. This is B<deprecated> and will be
624 removed in a future version.
626 =head2 remove_from_$rel
628 B<Currently only available for C<many-to-many> relationships.>
632 =item Arguments: $obj
636 my $role = $schema->resultset('Role')->find(1);
637 $actor->remove_from_roles($role);
638 # removes $role's My::DBIC::Schema::ActorRoles linking table row object
640 Removes the link between the current object and the related object. Note that
641 the related object itself won't be deleted unless you call ->delete() on
642 it. This method just removes the link between the two objects.
646 Matt S. Trout <mst@shadowcatsystems.co.uk>
650 You may distribute this code under the same terms as Perl itself.