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>.
98 An arrayref containing a list of accessors in the foreign class to create in
99 the main class. If, for example, you do the following:
101 MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes',
103 proxy => [ qw/notes/ ],
106 Then, assuming MyDB::Schema::LinerNotes has an accessor named notes, you can do:
108 my $cd = MyDB::Schema::CD->find(1);
109 $cd->notes('Notes go here'); # set notes -- LinerNotes object is
110 # created if it doesn't exist
114 Specifies the type of accessor that should be created for the relationship.
115 Valid values are C<single> (for when there is only a single related object),
116 C<multi> (when there can be many), and C<filter> (for when there is a single
117 related object, but you also want the relationship accessor to double as
118 a column accessor). For C<multi> accessors, an add_to_* method is also
119 created, which calls C<create_related> for the relationship.
121 =item is_foreign_key_constraint
123 If you are using L<SQL::Translator> to create SQL for you and you find that it
124 is creating constraints where it shouldn't, or not creating them where it
125 should, set this attribute to a true or false value to override the detection
126 of when to create constraints.
130 If C<cascade_copy> is true on a C<has_many> relationship for an
131 object, then when you copy the object all the related objects will
132 be copied too. To turn this behaviour off, pass C<< cascade_copy => 0 >>
133 in the C<$attr> hashref.
135 The behaviour defaults to C<< cascade_copy => 1 >> for C<has_many>
140 By default, DBIx::Class cascades deletes across C<has_many>,
141 C<has_one> and C<might_have> relationships. You can disable this
142 behaviour on a per-relationship basis by supplying
143 C<< cascade_delete => 0 >> in the relationship attributes.
145 The cascaded operations are performed after the requested delete,
146 so if your database has a constraint on the relationship, it will
147 have deleted/updated the related records or raised an exception
148 before DBIx::Class gets to perform the cascaded operation.
152 By default, DBIx::Class cascades updates across C<has_one> and
153 C<might_have> relationships. You can disable this behaviour on a
154 per-relationship basis by supplying C<< cascade_update => 0 >> in
155 the relationship attributes.
157 This is not a RDMS style cascade update - it purely means that when
158 an object has update called on it, all the related objects also
159 have update called. It will not change foreign keys automatically -
160 you must arrange to do this yourself.
162 =item on_delete / on_update
164 If you are using L<SQL::Translator> to create SQL for you, you can use these
165 attributes to explicitly set the desired C<ON DELETE> or C<ON UPDATE> constraint
166 type. If not supplied the SQLT parser will attempt to infer the constraint type by
167 interrogating the attributes of the B<opposite> relationship. For any 'multi'
168 relationship with C<< cascade_delete => 1 >>, the corresponding belongs_to
169 relationship will be created with an C<ON DELETE CASCADE> constraint. For any
170 relationship bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint
171 will be C<ON UPDATE CASCADE>. If you wish to disable this autodetection, and just
172 use the RDBMS' default constraint type, pass C<< on_delete => undef >> or
173 C<< on_delete => '' >>, and the same for C<on_update> respectively.
177 Tells L<SQL::Translator> that the foreign key constraint it creates should be
178 deferrable. In other words, the user may request that the constraint be ignored
179 until the end of the transaction. Currently, only the PostgreSQL producer
180 actually supports this.
184 Tells L<SQL::Translator> to add an index for this constraint. Can also be
185 specified globally in the args to L<DBIx::Class::Schema/deploy> or
186 L<DBIx::Class::Schema/create_ddl_dir>. Default is on, set to 0 to disable.
190 =head2 register_relationship
194 =item Arguments: $relname, $rel_info
198 Registers a relationship on the class. This is called internally by
199 DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
203 sub register_relationship { }
205 =head2 related_resultset
209 =item Arguments: $relationship_name
211 =item Return Value: $related_resultset
215 $rs = $cd->related_resultset('artist');
217 Returns a L<DBIx::Class::ResultSet> for the relationship named
222 sub related_resultset {
224 $self->throw_exception("Can't call *_related as class methods")
227 my $rel_info = $self->relationship_info($rel);
228 $self->throw_exception( "No such relationship ${rel}" )
231 return $self->{related_resultsets}{$rel} ||= do {
232 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
233 $attrs = { %{$rel_info->{attrs} || {}}, %$attrs };
235 $self->throw_exception( "Invalid query: @_" )
236 if (@_ > 1 && (@_ % 2 == 1));
237 my $query = ((@_ > 1) ? {@_} : shift);
239 my $source = $self->result_source;
241 # condition resolution may fail if an incomplete master-object prefetch
242 # is encountered - that is ok during prefetch construction (not yet in_storage)
244 $source->_resolve_condition( $rel_info->{cond}, $rel, $self )
247 if ($self->in_storage) {
248 $self->throw_exception ($_);
251 $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION; # RV
254 if ($cond eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) {
255 my $reverse = $source->reverse_relationship_info($rel);
256 foreach my $rev_rel (keys %$reverse) {
257 if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') {
258 $attrs->{related_objects}{$rev_rel} = [ $self ];
259 weaken $attrs->{related_object}{$rev_rel}[0];
261 $attrs->{related_objects}{$rev_rel} = $self;
262 weaken $attrs->{related_object}{$rev_rel};
266 if (ref $cond eq 'ARRAY') {
268 if (ref $_ eq 'HASH') {
270 foreach my $key (keys %$_) {
271 my $newkey = $key !~ /\./ ? "me.$key" : $key;
272 $hash->{$newkey} = $_->{$key};
279 } elsif (ref $cond eq 'HASH') {
280 foreach my $key (grep { ! /\./ } keys %$cond) {
281 $cond->{"me.$key"} = delete $cond->{$key};
284 $query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
285 $self->result_source->related_source($rel)->resultset->search(
291 =head2 search_related
293 @objects = $rs->search_related('relname', $cond, $attrs);
294 $objects_rs = $rs->search_related('relname', $cond, $attrs);
296 Run a search on a related resultset. The search will be restricted to the
297 item or items represented by the L<DBIx::Class::ResultSet> it was called
298 upon. This method can be called on a ResultSet, a Row or a ResultSource class.
303 return shift->related_resultset(shift)->search(@_);
306 =head2 search_related_rs
308 ( $objects_rs ) = $rs->search_related_rs('relname', $cond, $attrs);
310 This method works exactly the same as search_related, except that
311 it guarantees a resultset, even in list context.
315 sub search_related_rs {
316 return shift->related_resultset(shift)->search_rs(@_);
321 $obj->count_related('relname', $cond, $attrs);
323 Returns the count of all the items in the related resultset, restricted by the
324 current item or where conditions. Can be called on a
325 L<DBIx::Class::Manual::Glossary/"ResultSet"> or a
326 L<DBIx::Class::Manual::Glossary/"Row"> object.
332 return $self->search_related(@_)->count;
337 my $new_obj = $obj->new_related('relname', \%col_data);
339 Create a new item of the related foreign class. If called on a
340 L<Row|DBIx::Class::Manual::Glossary/"Row"> object, it will magically
341 set any foreign key columns of the new object to the related primary
342 key columns of the source object for you. The newly created item will
343 not be saved into your storage until you call L<DBIx::Class::Row/insert>
349 my ($self, $rel, $values, $attrs) = @_;
350 return $self->search_related($rel)->new($values, $attrs);
353 =head2 create_related
355 my $new_obj = $obj->create_related('relname', \%col_data);
357 Creates a new item, similarly to new_related, and also inserts the item's data
358 into your storage medium. See the distinction between C<create> and C<new>
359 in L<DBIx::Class::ResultSet> for details.
366 my $obj = $self->search_related($rel)->create(@_);
367 delete $self->{related_resultsets}->{$rel};
373 my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals);
375 Attempt to find a related object using its primary key or unique constraints.
376 See L<DBIx::Class::ResultSet/find> for details.
383 return $self->search_related($rel)->find(@_);
386 =head2 find_or_new_related
388 my $new_obj = $obj->find_or_new_related('relname', \%col_data);
390 Find an item of a related class. If none exists, instantiate a new item of the
391 related class. The object will not be saved into your storage until you call
392 L<DBIx::Class::Row/insert> on it.
396 sub find_or_new_related {
398 my $obj = $self->find_related(@_);
399 return defined $obj ? $obj : $self->new_related(@_);
402 =head2 find_or_create_related
404 my $new_obj = $obj->find_or_create_related('relname', \%col_data);
406 Find or create an item of a related class. See
407 L<DBIx::Class::ResultSet/find_or_create> for details.
411 sub find_or_create_related {
413 my $obj = $self->find_related(@_);
414 return (defined($obj) ? $obj : $self->create_related(@_));
417 =head2 update_or_create_related
419 my $updated_item = $obj->update_or_create_related('relname', \%col_data, \%attrs?);
421 Update or create an item of a related class. See
422 L<DBIx::Class::ResultSet/update_or_create> for details.
426 sub update_or_create_related {
429 return $self->related_resultset($rel)->update_or_create(@_);
432 =head2 set_from_related
434 $book->set_from_related('author', $author_obj);
435 $book->author($author_obj); ## same thing
437 Set column values on the current object, using related values from the given
438 related object. This is used to associate previously separate objects, for
439 example, to set the correct author for a book, find the Author object, then
440 call set_from_related on the book.
442 This is called internally when you pass existing objects as values to
443 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
445 The columns are only set in the local copy of the object, call L</update> to
446 set them in the storage.
450 sub set_from_related {
451 my ($self, $rel, $f_obj) = @_;
452 my $rel_info = $self->relationship_info($rel);
453 $self->throw_exception( "No such relationship ${rel}" ) unless $rel_info;
454 my $cond = $rel_info->{cond};
455 $self->throw_exception(
456 "set_from_related can only handle a hash condition; the ".
457 "condition for $rel is of type ".
458 (ref $cond ? ref $cond : 'plain scalar')
459 ) unless ref $cond eq 'HASH';
460 if (defined $f_obj) {
461 my $f_class = $rel_info->{class};
462 $self->throw_exception( "Object $f_obj isn't a ".$f_class )
463 unless blessed $f_obj and $f_obj->isa($f_class);
466 $self->result_source->_resolve_condition(
467 $rel_info->{cond}, $f_obj, $rel));
471 =head2 update_from_related
473 $book->update_from_related('author', $author_obj);
475 The same as L</"set_from_related">, but the changes are immediately updated
480 sub update_from_related {
482 $self->set_from_related(@_);
486 =head2 delete_related
488 $obj->delete_related('relname', $cond, $attrs);
490 Delete any related item subject to the given conditions.
496 my $obj = $self->search_related(@_)->delete;
497 delete $self->{related_resultsets}->{$_[0]};
503 B<Currently only available for C<has_many>, C<many-to-many> and 'multi' type
508 =item Arguments: ($foreign_vals | $obj), $link_vals?
512 my $role = $schema->resultset('Role')->find(1);
513 $actor->add_to_roles($role);
514 # creates a My::DBIC::Schema::ActorRoles linking table row object
516 $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
517 # creates a new My::DBIC::Schema::Role row object and the linking table
518 # object with an extra column in the link
520 Adds a linking table object for C<$obj> or C<$foreign_vals>. If the first
521 argument is a hash reference, the related object is created first with the
522 column values in the hash. If an object reference is given, just the linking
523 table object is created. In either case, any additional column values for the
524 linking table object can be specified in C<$link_vals>.
528 B<Currently only available for C<many-to-many> relationships.>
532 =item Arguments: (\@hashrefs | \@objs), $link_vals?
536 my $actor = $schema->resultset('Actor')->find(1);
537 my @roles = $schema->resultset('Role')->search({ role =>
538 { '-in' => ['Fred', 'Barney'] } } );
540 $actor->set_roles(\@roles);
541 # Replaces all of $actor's previous roles with the two named
543 $actor->set_roles(\@roles, { salary => 15_000_000 });
544 # Sets a column in the link table for all roles
547 Replace all the related objects with the given reference to a list of
548 objects. This does a C<delete> B<on the link table resultset> to remove the
549 association between the current object and all related objects, then calls
550 C<add_to_$rel> repeatedly to link all the new objects.
552 Note that this means that this method will B<not> delete any objects in the
553 table on the right side of the relation, merely that it will delete the link
556 Due to a mistake in the original implementation of this method, it will also
557 accept a list of objects or hash references. This is B<deprecated> and will be
558 removed in a future version.
560 =head2 remove_from_$rel
562 B<Currently only available for C<many-to-many> relationships.>
566 =item Arguments: $obj
570 my $role = $schema->resultset('Role')->find(1);
571 $actor->remove_from_roles($role);
572 # removes $role's My::DBIC::Schema::ActorRoles linking table row object
574 Removes the link between the current object and the related object. Note that
575 the related object itself won't be deleted unless you call ->delete() on
576 it. This method just removes the link between the two objects.
580 Matt S. Trout <mst@shadowcatsystems.co.uk>
584 You may distribute this code under the same terms as Perl itself.