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.
125 =item on_delete / on_update
127 If you are using L<SQL::Translator> to create SQL for you, you can use these
128 attributes to explicitly set the desired C<ON DELETE> or C<ON UPDATE> constraint
129 type. If not supplied the SQLT parser will attempt to infer the constraint type by
130 interrogating the attributes of the B<opposite> relationship. For any 'multi'
131 relationship with C<< cascade_delete => 1 >>, the corresponding belongs_to
132 relationship will be created with an C<ON DELETE CASCADE> constraint. For any
133 relationship bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint
134 will be C<ON UPDATE CASCADE>. If you wish to disable this autodetection, and just
135 use the RDBMS' default constraint type, pass C<< on_delete => undef >> or
136 C<< on_delete => '' >>, and the same for C<on_update> respectively.
140 Tells L<SQL::Translator> that the foreign key constraint it creates should be
141 deferrable. In other words, the user may request that the constraint be ignored
142 until the end of the transaction. Currently, only the PostgreSQL producer
143 actually supports this.
147 Tells L<SQL::Translator> to add an index for this constraint. Can also be
148 specified globally in the args to L<DBIx::Class::Schema/deploy> or
149 L<DBIx::Class::Schema/create_ddl_dir>. Default is on, set to 0 to disable.
153 =head2 register_relationship
157 =item Arguments: $relname, $rel_info
161 Registers a relationship on the class. This is called internally by
162 DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
166 sub register_relationship { }
168 =head2 related_resultset
172 =item Arguments: $relationship_name
174 =item Return Value: $related_resultset
178 $rs = $cd->related_resultset('artist');
180 Returns a L<DBIx::Class::ResultSet> for the relationship named
185 sub related_resultset {
187 $self->throw_exception("Can't call *_related as class methods")
190 my $rel_info = $self->relationship_info($rel);
191 $self->throw_exception( "No such relationship ${rel}" )
194 return $self->{related_resultsets}{$rel} ||= do {
195 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
196 $attrs = { %{$rel_info->{attrs} || {}}, %$attrs };
198 $self->throw_exception( "Invalid query: @_" )
199 if (@_ > 1 && (@_ % 2 == 1));
200 my $query = ((@_ > 1) ? {@_} : shift);
202 my $source = $self->result_source;
204 # condition resolution may fail if an incomplete master-object prefetch
205 # is encountered - that is ok during prefetch construction (not yet in_storage)
206 my $cond = eval { $source->_resolve_condition( $rel_info->{cond}, $rel, $self ) };
208 if ($self->in_storage) {
209 $self->throw_exception ($err);
212 $cond = $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION;
216 if ($cond eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) {
217 my $reverse = $source->reverse_relationship_info($rel);
218 foreach my $rev_rel (keys %$reverse) {
219 if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') {
220 $attrs->{related_objects}{$rev_rel} = [ $self ];
221 Scalar::Util::weaken($attrs->{related_object}{$rev_rel}[0]);
223 $attrs->{related_objects}{$rev_rel} = $self;
224 Scalar::Util::weaken($attrs->{related_object}{$rev_rel});
228 if (ref $cond eq 'ARRAY') {
230 if (ref $_ eq 'HASH') {
232 foreach my $key (keys %$_) {
233 my $newkey = $key !~ /\./ ? "me.$key" : $key;
234 $hash->{$newkey} = $_->{$key};
241 } elsif (ref $cond eq 'HASH') {
242 foreach my $key (grep { ! /\./ } keys %$cond) {
243 $cond->{"me.$key"} = delete $cond->{$key};
246 $query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
247 $self->result_source->related_source($rel)->resultset->search(
253 =head2 search_related
255 @objects = $rs->search_related('relname', $cond, $attrs);
256 $objects_rs = $rs->search_related('relname', $cond, $attrs);
258 Run a search on a related resultset. The search will be restricted to the
259 item or items represented by the L<DBIx::Class::ResultSet> it was called
260 upon. This method can be called on a ResultSet, a Row or a ResultSource class.
265 return shift->related_resultset(shift)->search(@_);
268 =head2 search_related_rs
270 ( $objects_rs ) = $rs->search_related_rs('relname', $cond, $attrs);
272 This method works exactly the same as search_related, except that
273 it guarantees a resultset, even in list context.
277 sub search_related_rs {
278 return shift->related_resultset(shift)->search_rs(@_);
283 $obj->count_related('relname', $cond, $attrs);
285 Returns the count of all the items in the related resultset, restricted by the
286 current item or where conditions. Can be called on a
287 L<DBIx::Class::Manual::Glossary/"ResultSet"> or a
288 L<DBIx::Class::Manual::Glossary/"Row"> object.
294 return $self->search_related(@_)->count;
299 my $new_obj = $obj->new_related('relname', \%col_data);
301 Create a new item of the related foreign class. If called on a
302 L<Row|DBIx::Class::Manual::Glossary/"Row"> object, it will magically
303 set any foreign key columns of the new object to the related primary
304 key columns of the source object for you. The newly created item will
305 not be saved into your storage until you call L<DBIx::Class::Row/insert>
311 my ($self, $rel, $values, $attrs) = @_;
312 return $self->search_related($rel)->new($values, $attrs);
315 =head2 create_related
317 my $new_obj = $obj->create_related('relname', \%col_data);
319 Creates a new item, similarly to new_related, and also inserts the item's data
320 into your storage medium. See the distinction between C<create> and C<new>
321 in L<DBIx::Class::ResultSet> for details.
328 my $obj = $self->search_related($rel)->create(@_);
329 delete $self->{related_resultsets}->{$rel};
335 my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals);
337 Attempt to find a related object using its primary key or unique constraints.
338 See L<DBIx::Class::ResultSet/find> for details.
345 return $self->search_related($rel)->find(@_);
348 =head2 find_or_new_related
350 my $new_obj = $obj->find_or_new_related('relname', \%col_data);
352 Find an item of a related class. If none exists, instantiate a new item of the
353 related class. The object will not be saved into your storage until you call
354 L<DBIx::Class::Row/insert> on it.
358 sub find_or_new_related {
360 my $obj = $self->find_related(@_);
361 return defined $obj ? $obj : $self->new_related(@_);
364 =head2 find_or_create_related
366 my $new_obj = $obj->find_or_create_related('relname', \%col_data);
368 Find or create an item of a related class. See
369 L<DBIx::Class::ResultSet/find_or_create> for details.
373 sub find_or_create_related {
375 my $obj = $self->find_related(@_);
376 return (defined($obj) ? $obj : $self->create_related(@_));
379 =head2 update_or_create_related
381 my $updated_item = $obj->update_or_create_related('relname', \%col_data, \%attrs?);
383 Update or create an item of a related class. See
384 L<DBIx::Class::ResultSet/update_or_create> for details.
388 sub update_or_create_related {
391 return $self->related_resultset($rel)->update_or_create(@_);
394 =head2 set_from_related
396 $book->set_from_related('author', $author_obj);
397 $book->author($author_obj); ## same thing
399 Set column values on the current object, using related values from the given
400 related object. This is used to associate previously separate objects, for
401 example, to set the correct author for a book, find the Author object, then
402 call set_from_related on the book.
404 This is called internally when you pass existing objects as values to
405 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
407 The columns are only set in the local copy of the object, call L</update> to
408 set them in the storage.
412 sub set_from_related {
413 my ($self, $rel, $f_obj) = @_;
414 my $rel_info = $self->relationship_info($rel);
415 $self->throw_exception( "No such relationship ${rel}" ) unless $rel_info;
416 my $cond = $rel_info->{cond};
417 $self->throw_exception(
418 "set_from_related can only handle a hash condition; the ".
419 "condition for $rel is of type ".
420 (ref $cond ? ref $cond : 'plain scalar')
421 ) unless ref $cond eq 'HASH';
422 if (defined $f_obj) {
423 my $f_class = $rel_info->{class};
424 $self->throw_exception( "Object $f_obj isn't a ".$f_class )
425 unless Scalar::Util::blessed($f_obj) and $f_obj->isa($f_class);
428 $self->result_source->_resolve_condition(
429 $rel_info->{cond}, $f_obj, $rel));
433 =head2 update_from_related
435 $book->update_from_related('author', $author_obj);
437 The same as L</"set_from_related">, but the changes are immediately updated
442 sub update_from_related {
444 $self->set_from_related(@_);
448 =head2 delete_related
450 $obj->delete_related('relname', $cond, $attrs);
452 Delete any related item subject to the given conditions.
458 my $obj = $self->search_related(@_)->delete;
459 delete $self->{related_resultsets}->{$_[0]};
465 B<Currently only available for C<has_many>, C<many-to-many> and 'multi' type
470 =item Arguments: ($foreign_vals | $obj), $link_vals?
474 my $role = $schema->resultset('Role')->find(1);
475 $actor->add_to_roles($role);
476 # creates a My::DBIC::Schema::ActorRoles linking table row object
478 $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
479 # creates a new My::DBIC::Schema::Role row object and the linking table
480 # object with an extra column in the link
482 Adds a linking table object for C<$obj> or C<$foreign_vals>. If the first
483 argument is a hash reference, the related object is created first with the
484 column values in the hash. If an object reference is given, just the linking
485 table object is created. In either case, any additional column values for the
486 linking table object can be specified in C<$link_vals>.
490 B<Currently only available for C<many-to-many> relationships.>
494 =item Arguments: (\@hashrefs | \@objs), $link_vals?
498 my $actor = $schema->resultset('Actor')->find(1);
499 my @roles = $schema->resultset('Role')->search({ role =>
500 { '-in' => ['Fred', 'Barney'] } } );
502 $actor->set_roles(\@roles);
503 # Replaces all of $actor's previous roles with the two named
505 $actor->set_roles(\@roles, { salary => 15_000_000 });
506 # Sets a column in the link table for all roles
509 Replace all the related objects with the given reference to a list of
510 objects. This does a C<delete> B<on the link table resultset> to remove the
511 association between the current object and all related objects, then calls
512 C<add_to_$rel> repeatedly to link all the new objects.
514 Note that this means that this method will B<not> delete any objects in the
515 table on the right side of the relation, merely that it will delete the link
518 Due to a mistake in the original implementation of this method, it will also
519 accept a list of objects or hash references. This is B<deprecated> and will be
520 removed in a future version.
522 =head2 remove_from_$rel
524 B<Currently only available for C<many-to-many> relationships.>
528 =item Arguments: $obj
532 my $role = $schema->resultset('Role')->find(1);
533 $actor->remove_from_roles($role);
534 # removes $role's My::DBIC::Schema::ActorRoles linking table row object
536 Removes the link between the current object and the related object. Note that
537 the related object itself won't be deleted unless you call ->delete() on
538 it. This method just removes the link between the two objects.
542 Matt S. Trout <mst@shadowcatsystems.co.uk>
546 You may distribute this code under the same terms as Perl itself.