1 package DBIx::Class::Relationship::Base;
7 use base qw/DBIx::Class/;
13 DBIx::Class::Relationship::Base - Inter-table relationships
19 This class provides methods to describe the relationships between the
20 tables in your database model. These are the "bare bones" relationships
21 methods, for predefined ones, look in L<DBIx::Class::Relationship>.
25 =head2 add_relationship
29 =item Arguments: 'relname', 'Foreign::Class', $cond, $attrs
33 __PACKAGE__->add_relationship('relname', 'Foreign::Class', $cond, $attrs);
37 The condition needs to be an L<SQL::Abstract>-style representation of the
38 join between the tables. When resolving the condition for use in a C<JOIN>,
39 keys using the pseudo-table C<foreign> are resolved to mean "the Table on the
40 other side of the relationship", and values using the pseudo-table C<self>
41 are resolved to mean "the Table this class is representing". Other
42 restrictions, such as by value, sub-select and other tables, may also be
43 used. Please check your database for C<JOIN> parameter support.
45 For example, if you're creating a relationship from C<Author> to C<Book>, where
46 the C<Book> table has a column C<author_id> containing the ID of the C<Author>
49 { 'foreign.author_id' => 'self.id' }
51 will result in the C<JOIN> clause
53 author me JOIN book book ON book.author_id = me.id
55 For multi-column foreign keys, you will need to specify a C<foreign>-to-C<self>
56 mapping for each column in the key. For example, if you're creating a
57 relationship from C<Book> to C<Edition>, where the C<Edition> table refers to a
58 publisher and a type (e.g. "paperback"):
61 'foreign.publisher_id' => 'self.publisher_id',
62 'foreign.type_id' => 'self.type_id',
65 This will result in the C<JOIN> clause:
67 book me JOIN edition edition ON edition.publisher_id = me.publisher_id
68 AND edition.type_id = me.type_id
70 Each key-value pair provided in a hashref will be used as C<AND>ed conditions.
71 To add an C<OR>ed condition, use an arrayref of hashrefs. See the
72 L<SQL::Abstract> documentation for more details.
76 The L<standard ResultSet attributes|DBIx::Class::ResultSet/ATTRIBUTES> may
77 be used as relationship attributes. In particular, the 'where' attribute is
78 useful for filtering relationships:
80 __PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User',
81 { 'foreign.user_id' => 'self.user_id' },
82 { where => { valid => 1 } }
85 The following attributes are also valid:
91 Explicitly specifies the type of join to use in the relationship. Any SQL
92 join type is valid, e.g. C<LEFT> or C<RIGHT>. It will be placed in the SQL
93 command immediately before C<JOIN>.
97 An arrayref containing a list of accessors in the foreign class to create in
98 the main class. If, for example, you do the following:
100 MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes',
102 proxy => [ qw/notes/ ],
105 Then, assuming MyDB::Schema::LinerNotes has an accessor named notes, you can do:
107 my $cd = MyDB::Schema::CD->find(1);
108 $cd->notes('Notes go here'); # set notes -- LinerNotes object is
109 # created if it doesn't exist
113 Specifies the type of accessor that should be created for the relationship.
114 Valid values are C<single> (for when there is only a single related object),
115 C<multi> (when there can be many), and C<filter> (for when there is a single
116 related object, but you also want the relationship accessor to double as
117 a column accessor). For C<multi> accessors, an add_to_* method is also
118 created, which calls C<create_related> for the relationship.
120 =item is_foreign_key_constraint
122 If you are using L<SQL::Translator> to create SQL for you and you find that it
123 is creating constraints where it shouldn't, or not creating them where it
124 should, set this attribute to a true or false value to override the detection
125 of when to create constraints.
129 If C<cascade_copy> is true on a C<has_many> relationship for an
130 object, then when you copy the object all the related objects will
131 be copied too. To turn this behaviour off, pass C<< cascade_copy => 0 >>
132 in the C<$attr> hashref.
134 The behaviour defaults to C<< cascade_copy => 1 >> for C<has_many>
139 By default, DBIx::Class cascades deletes across C<has_many>,
140 C<has_one> and C<might_have> relationships. You can disable this
141 behaviour on a per-relationship basis by supplying
142 C<< cascade_delete => 0 >> in the relationship attributes.
144 The cascaded operations are performed after the requested delete,
145 so if your database has a constraint on the relationship, it will
146 have deleted/updated the related records or raised an exception
147 before DBIx::Class gets to perform the cascaded operation.
151 By default, DBIx::Class cascades updates across C<has_one> and
152 C<might_have> relationships. You can disable this behaviour on a
153 per-relationship basis by supplying C<< cascade_update => 0 >> in
154 the relationship attributes.
156 This is not a RDMS style cascade update - it purely means that when
157 an object has update called on it, all the related objects also
158 have update called. It will not change foreign keys automatically -
159 you must arrange to do this yourself.
161 =item on_delete / on_update
163 If you are using L<SQL::Translator> to create SQL for you, you can use these
164 attributes to explicitly set the desired C<ON DELETE> or C<ON UPDATE> constraint
165 type. If not supplied the SQLT parser will attempt to infer the constraint type by
166 interrogating the attributes of the B<opposite> relationship. For any 'multi'
167 relationship with C<< cascade_delete => 1 >>, the corresponding belongs_to
168 relationship will be created with an C<ON DELETE CASCADE> constraint. For any
169 relationship bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint
170 will be C<ON UPDATE CASCADE>. If you wish to disable this autodetection, and just
171 use the RDBMS' default constraint type, pass C<< on_delete => undef >> or
172 C<< on_delete => '' >>, and the same for C<on_update> respectively.
176 Tells L<SQL::Translator> that the foreign key constraint it creates should be
177 deferrable. In other words, the user may request that the constraint be ignored
178 until the end of the transaction. Currently, only the PostgreSQL producer
179 actually supports this.
183 Tells L<SQL::Translator> to add an index for this constraint. Can also be
184 specified globally in the args to L<DBIx::Class::Schema/deploy> or
185 L<DBIx::Class::Schema/create_ddl_dir>. Default is on, set to 0 to disable.
189 =head2 register_relationship
193 =item Arguments: $relname, $rel_info
197 Registers a relationship on the class. This is called internally by
198 DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
202 sub register_relationship { }
204 =head2 related_resultset
208 =item Arguments: $relationship_name
210 =item Return Value: $related_resultset
214 $rs = $cd->related_resultset('artist');
216 Returns a L<DBIx::Class::ResultSet> for the relationship named
221 sub related_resultset {
223 $self->throw_exception("Can't call *_related as class methods")
226 my $rel_info = $self->relationship_info($rel);
227 $self->throw_exception( "No such relationship ${rel}" )
230 return $self->{related_resultsets}{$rel} ||= do {
231 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
232 $attrs = { %{$rel_info->{attrs} || {}}, %$attrs };
234 $self->throw_exception( "Invalid query: @_" )
235 if (@_ > 1 && (@_ % 2 == 1));
236 my $query = ((@_ > 1) ? {@_} : shift);
238 my $source = $self->result_source;
240 # condition resolution may fail if an incomplete master-object prefetch
241 # is encountered - that is ok during prefetch construction (not yet in_storage)
243 $source->_resolve_condition( $rel_info->{cond}, $rel, $self )
246 if ($self->in_storage) {
247 $self->throw_exception ($_);
250 $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION; # RV
253 if ($cond eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) {
254 my $reverse = $source->reverse_relationship_info($rel);
255 foreach my $rev_rel (keys %$reverse) {
256 if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') {
257 $attrs->{related_objects}{$rev_rel} = [ $self ];
258 Scalar::Util::weaken($attrs->{related_object}{$rev_rel}[0]);
260 $attrs->{related_objects}{$rev_rel} = $self;
261 Scalar::Util::weaken($attrs->{related_object}{$rev_rel});
265 if (ref $cond eq 'ARRAY') {
267 if (ref $_ eq 'HASH') {
269 foreach my $key (keys %$_) {
270 my $newkey = $key !~ /\./ ? "me.$key" : $key;
271 $hash->{$newkey} = $_->{$key};
278 } elsif (ref $cond eq 'HASH') {
279 foreach my $key (grep { ! /\./ } keys %$cond) {
280 $cond->{"me.$key"} = delete $cond->{$key};
283 $query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
284 $self->result_source->related_source($rel)->resultset->search(
290 =head2 search_related
292 @objects = $rs->search_related('relname', $cond, $attrs);
293 $objects_rs = $rs->search_related('relname', $cond, $attrs);
295 Run a search on a related resultset. The search will be restricted to the
296 item or items represented by the L<DBIx::Class::ResultSet> it was called
297 upon. This method can be called on a ResultSet, a Row or a ResultSource class.
302 return shift->related_resultset(shift)->search(@_);
305 =head2 search_related_rs
307 ( $objects_rs ) = $rs->search_related_rs('relname', $cond, $attrs);
309 This method works exactly the same as search_related, except that
310 it guarantees a resultset, even in list context.
314 sub search_related_rs {
315 return shift->related_resultset(shift)->search_rs(@_);
320 $obj->count_related('relname', $cond, $attrs);
322 Returns the count of all the items in the related resultset, restricted by the
323 current item or where conditions. Can be called on a
324 L<DBIx::Class::Manual::Glossary/"ResultSet"> or a
325 L<DBIx::Class::Manual::Glossary/"Row"> object.
331 return $self->search_related(@_)->count;
336 my $new_obj = $obj->new_related('relname', \%col_data);
338 Create a new item of the related foreign class. If called on a
339 L<Row|DBIx::Class::Manual::Glossary/"Row"> object, it will magically
340 set any foreign key columns of the new object to the related primary
341 key columns of the source object for you. The newly created item will
342 not be saved into your storage until you call L<DBIx::Class::Row/insert>
348 my ($self, $rel, $values, $attrs) = @_;
349 return $self->search_related($rel)->new($values, $attrs);
352 =head2 create_related
354 my $new_obj = $obj->create_related('relname', \%col_data);
356 Creates a new item, similarly to new_related, and also inserts the item's data
357 into your storage medium. See the distinction between C<create> and C<new>
358 in L<DBIx::Class::ResultSet> for details.
365 my $obj = $self->search_related($rel)->create(@_);
366 delete $self->{related_resultsets}->{$rel};
372 my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals);
374 Attempt to find a related object using its primary key or unique constraints.
375 See L<DBIx::Class::ResultSet/find> for details.
382 return $self->search_related($rel)->find(@_);
385 =head2 find_or_new_related
387 my $new_obj = $obj->find_or_new_related('relname', \%col_data);
389 Find an item of a related class. If none exists, instantiate a new item of the
390 related class. The object will not be saved into your storage until you call
391 L<DBIx::Class::Row/insert> on it.
395 sub find_or_new_related {
397 my $obj = $self->find_related(@_);
398 return defined $obj ? $obj : $self->new_related(@_);
401 =head2 find_or_create_related
403 my $new_obj = $obj->find_or_create_related('relname', \%col_data);
405 Find or create an item of a related class. See
406 L<DBIx::Class::ResultSet/find_or_create> for details.
410 sub find_or_create_related {
412 my $obj = $self->find_related(@_);
413 return (defined($obj) ? $obj : $self->create_related(@_));
416 =head2 update_or_create_related
418 my $updated_item = $obj->update_or_create_related('relname', \%col_data, \%attrs?);
420 Update or create an item of a related class. See
421 L<DBIx::Class::ResultSet/update_or_create> for details.
425 sub update_or_create_related {
428 return $self->related_resultset($rel)->update_or_create(@_);
431 =head2 set_from_related
433 $book->set_from_related('author', $author_obj);
434 $book->author($author_obj); ## same thing
436 Set column values on the current object, using related values from the given
437 related object. This is used to associate previously separate objects, for
438 example, to set the correct author for a book, find the Author object, then
439 call set_from_related on the book.
441 This is called internally when you pass existing objects as values to
442 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
444 The columns are only set in the local copy of the object, call L</update> to
445 set them in the storage.
449 sub set_from_related {
450 my ($self, $rel, $f_obj) = @_;
451 my $rel_info = $self->relationship_info($rel);
452 $self->throw_exception( "No such relationship ${rel}" ) unless $rel_info;
453 my $cond = $rel_info->{cond};
454 $self->throw_exception(
455 "set_from_related can only handle a hash condition; the ".
456 "condition for $rel is of type ".
457 (ref $cond ? ref $cond : 'plain scalar')
458 ) unless ref $cond eq 'HASH';
459 if (defined $f_obj) {
460 my $f_class = $rel_info->{class};
461 $self->throw_exception( "Object $f_obj isn't a ".$f_class )
462 unless Scalar::Util::blessed($f_obj) and $f_obj->isa($f_class);
465 $self->result_source->_resolve_condition(
466 $rel_info->{cond}, $f_obj, $rel));
470 =head2 update_from_related
472 $book->update_from_related('author', $author_obj);
474 The same as L</"set_from_related">, but the changes are immediately updated
479 sub update_from_related {
481 $self->set_from_related(@_);
485 =head2 delete_related
487 $obj->delete_related('relname', $cond, $attrs);
489 Delete any related item subject to the given conditions.
495 my $obj = $self->search_related(@_)->delete;
496 delete $self->{related_resultsets}->{$_[0]};
502 B<Currently only available for C<has_many>, C<many-to-many> and 'multi' type
507 =item Arguments: ($foreign_vals | $obj), $link_vals?
511 my $role = $schema->resultset('Role')->find(1);
512 $actor->add_to_roles($role);
513 # creates a My::DBIC::Schema::ActorRoles linking table row object
515 $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
516 # creates a new My::DBIC::Schema::Role row object and the linking table
517 # object with an extra column in the link
519 Adds a linking table object for C<$obj> or C<$foreign_vals>. If the first
520 argument is a hash reference, the related object is created first with the
521 column values in the hash. If an object reference is given, just the linking
522 table object is created. In either case, any additional column values for the
523 linking table object can be specified in C<$link_vals>.
527 B<Currently only available for C<many-to-many> relationships.>
531 =item Arguments: (\@hashrefs | \@objs), $link_vals?
535 my $actor = $schema->resultset('Actor')->find(1);
536 my @roles = $schema->resultset('Role')->search({ role =>
537 { '-in' => ['Fred', 'Barney'] } } );
539 $actor->set_roles(\@roles);
540 # Replaces all of $actor's previous roles with the two named
542 $actor->set_roles(\@roles, { salary => 15_000_000 });
543 # Sets a column in the link table for all roles
546 Replace all the related objects with the given reference to a list of
547 objects. This does a C<delete> B<on the link table resultset> to remove the
548 association between the current object and all related objects, then calls
549 C<add_to_$rel> repeatedly to link all the new objects.
551 Note that this means that this method will B<not> delete any objects in the
552 table on the right side of the relation, merely that it will delete the link
555 Due to a mistake in the original implementation of this method, it will also
556 accept a list of objects or hash references. This is B<deprecated> and will be
557 removed in a future version.
559 =head2 remove_from_$rel
561 B<Currently only available for C<many-to-many> relationships.>
565 =item Arguments: $obj
569 my $role = $schema->resultset('Role')->find(1);
570 $actor->remove_from_roles($role);
571 # removes $role's My::DBIC::Schema::ActorRoles linking table row object
573 Removes the link between the current object and the related object. Note that
574 the related object itself won't be deleted unless you call ->delete() on
575 it. This method just removes the link between the two objects.
579 Matt S. Trout <mst@shadowcatsystems.co.uk>
583 You may distribute this code under the same terms as Perl itself.