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 $source->_resolve_condition( $rel_info->{cond}, $rel, $self )
270 if ($self->in_storage) {
271 $self->throw_exception ($_);
274 $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION; # RV
277 if ($cond eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) {
278 my $reverse = $source->reverse_relationship_info($rel);
279 foreach my $rev_rel (keys %$reverse) {
280 if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') {
281 $attrs->{related_objects}{$rev_rel} = [ $self ];
282 weaken $attrs->{related_object}{$rev_rel}[0];
284 $attrs->{related_objects}{$rev_rel} = $self;
285 weaken $attrs->{related_object}{$rev_rel};
289 if (ref $cond eq 'ARRAY') {
291 if (ref $_ eq 'HASH') {
293 foreach my $key (keys %$_) {
294 my $newkey = $key !~ /\./ ? "me.$key" : $key;
295 $hash->{$newkey} = $_->{$key};
302 } elsif (ref $cond eq 'HASH') {
303 foreach my $key (grep { ! /\./ } keys %$cond) {
304 $cond->{"me.$key"} = delete $cond->{$key};
307 $query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
308 $self->result_source->related_source($rel)->resultset->search(
314 =head2 search_related
316 @objects = $rs->search_related('relname', $cond, $attrs);
317 $objects_rs = $rs->search_related('relname', $cond, $attrs);
319 Run a search on a related resultset. The search will be restricted to the
320 item or items represented by the L<DBIx::Class::ResultSet> it was called
321 upon. This method can be called on a ResultSet, a Row or a ResultSource class.
326 return shift->related_resultset(shift)->search(@_);
329 =head2 search_related_rs
331 ( $objects_rs ) = $rs->search_related_rs('relname', $cond, $attrs);
333 This method works exactly the same as search_related, except that
334 it guarantees a resultset, even in list context.
338 sub search_related_rs {
339 return shift->related_resultset(shift)->search_rs(@_);
344 $obj->count_related('relname', $cond, $attrs);
346 Returns the count of all the items in the related resultset, restricted by the
347 current item or where conditions. Can be called on a
348 L<DBIx::Class::Manual::Glossary/"ResultSet"> or a
349 L<DBIx::Class::Manual::Glossary/"Row"> object.
355 return $self->search_related(@_)->count;
360 my $new_obj = $obj->new_related('relname', \%col_data);
362 Create a new item of the related foreign class. If called on a
363 L<Row|DBIx::Class::Manual::Glossary/"Row"> object, it will magically
364 set any foreign key columns of the new object to the related primary
365 key columns of the source object for you. The newly created item will
366 not be saved into your storage until you call L<DBIx::Class::Row/insert>
372 my ($self, $rel, $values, $attrs) = @_;
373 return $self->search_related($rel)->new($values, $attrs);
376 =head2 create_related
378 my $new_obj = $obj->create_related('relname', \%col_data);
380 Creates a new item, similarly to new_related, and also inserts the item's data
381 into your storage medium. See the distinction between C<create> and C<new>
382 in L<DBIx::Class::ResultSet> for details.
389 my $obj = $self->search_related($rel)->create(@_);
390 delete $self->{related_resultsets}->{$rel};
396 my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals);
398 Attempt to find a related object using its primary key or unique constraints.
399 See L<DBIx::Class::ResultSet/find> for details.
406 return $self->search_related($rel)->find(@_);
409 =head2 find_or_new_related
411 my $new_obj = $obj->find_or_new_related('relname', \%col_data);
413 Find an item of a related class. If none exists, instantiate a new item of the
414 related class. The object will not be saved into your storage until you call
415 L<DBIx::Class::Row/insert> on it.
419 sub find_or_new_related {
421 my $obj = $self->find_related(@_);
422 return defined $obj ? $obj : $self->new_related(@_);
425 =head2 find_or_create_related
427 my $new_obj = $obj->find_or_create_related('relname', \%col_data);
429 Find or create an item of a related class. See
430 L<DBIx::Class::ResultSet/find_or_create> for details.
434 sub find_or_create_related {
436 my $obj = $self->find_related(@_);
437 return (defined($obj) ? $obj : $self->create_related(@_));
440 =head2 update_or_create_related
442 my $updated_item = $obj->update_or_create_related('relname', \%col_data, \%attrs?);
444 Update or create an item of a related class. See
445 L<DBIx::Class::ResultSet/update_or_create> for details.
449 sub update_or_create_related {
452 return $self->related_resultset($rel)->update_or_create(@_);
455 =head2 set_from_related
457 $book->set_from_related('author', $author_obj);
458 $book->author($author_obj); ## same thing
460 Set column values on the current object, using related values from the given
461 related object. This is used to associate previously separate objects, for
462 example, to set the correct author for a book, find the Author object, then
463 call set_from_related on the book.
465 This is called internally when you pass existing objects as values to
466 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
468 The columns are only set in the local copy of the object, call L</update> to
469 set them in the storage.
473 sub set_from_related {
474 my ($self, $rel, $f_obj) = @_;
475 my $rel_info = $self->relationship_info($rel);
476 $self->throw_exception( "No such relationship ${rel}" ) unless $rel_info;
477 my $cond = $rel_info->{cond};
478 $self->throw_exception(
479 "set_from_related can only handle a hash condition; the ".
480 "condition for $rel is of type ".
481 (ref $cond ? ref $cond : 'plain scalar')
482 ) unless ref $cond eq 'HASH';
483 if (defined $f_obj) {
484 my $f_class = $rel_info->{class};
485 $self->throw_exception( "Object $f_obj isn't a ".$f_class )
486 unless blessed $f_obj and $f_obj->isa($f_class);
489 $self->result_source->_resolve_condition(
490 $rel_info->{cond}, $f_obj, $rel));
494 =head2 update_from_related
496 $book->update_from_related('author', $author_obj);
498 The same as L</"set_from_related">, but the changes are immediately updated
503 sub update_from_related {
505 $self->set_from_related(@_);
509 =head2 delete_related
511 $obj->delete_related('relname', $cond, $attrs);
513 Delete any related item subject to the given conditions.
519 my $obj = $self->search_related(@_)->delete;
520 delete $self->{related_resultsets}->{$_[0]};
526 B<Currently only available for C<has_many>, C<many-to-many> and 'multi' type
531 =item Arguments: ($foreign_vals | $obj), $link_vals?
535 my $role = $schema->resultset('Role')->find(1);
536 $actor->add_to_roles($role);
537 # creates a My::DBIC::Schema::ActorRoles linking table row object
539 $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
540 # creates a new My::DBIC::Schema::Role row object and the linking table
541 # object with an extra column in the link
543 Adds a linking table object for C<$obj> or C<$foreign_vals>. If the first
544 argument is a hash reference, the related object is created first with the
545 column values in the hash. If an object reference is given, just the linking
546 table object is created. In either case, any additional column values for the
547 linking table object can be specified in C<$link_vals>.
551 B<Currently only available for C<many-to-many> relationships.>
555 =item Arguments: (\@hashrefs | \@objs), $link_vals?
559 my $actor = $schema->resultset('Actor')->find(1);
560 my @roles = $schema->resultset('Role')->search({ role =>
561 { '-in' => ['Fred', 'Barney'] } } );
563 $actor->set_roles(\@roles);
564 # Replaces all of $actor's previous roles with the two named
566 $actor->set_roles(\@roles, { salary => 15_000_000 });
567 # Sets a column in the link table for all roles
570 Replace all the related objects with the given reference to a list of
571 objects. This does a C<delete> B<on the link table resultset> to remove the
572 association between the current object and all related objects, then calls
573 C<add_to_$rel> repeatedly to link all the new objects.
575 Note that this means that this method will B<not> delete any objects in the
576 table on the right side of the relation, merely that it will delete the link
579 Due to a mistake in the original implementation of this method, it will also
580 accept a list of objects or hash references. This is B<deprecated> and will be
581 removed in a future version.
583 =head2 remove_from_$rel
585 B<Currently only available for C<many-to-many> relationships.>
589 =item Arguments: $obj
593 my $role = $schema->resultset('Role')->find(1);
594 $actor->remove_from_roles($role);
595 # removes $role's My::DBIC::Schema::ActorRoles linking table row object
597 Removes the link between the current object and the related object. Note that
598 the related object itself won't be deleted unless you call ->delete() on
599 it. This method just removes the link between the two objects.
603 Matt S. Trout <mst@shadowcatsystems.co.uk>
607 You may distribute this code under the same terms as Perl itself.