1 package DBIx::Class::Relationship::Base;
7 use base qw/DBIx::Class/;
12 DBIx::Class::Relationship::Base - Inter-table relationships
18 This class provides methods to describe the relationships between the
19 tables in your database model. These are the "bare bones" relationships
20 methods, for predefined ones, look in L<DBIx::Class::Relationship>.
24 =head2 add_relationship
28 =item Arguments: 'relname', 'Foreign::Class', $cond, $attrs
32 __PACKAGE__->add_relationship('relname', 'Foreign::Class', $cond, $attrs);
36 The condition needs to be an L<SQL::Abstract>-style representation of the
37 join between the tables. When resolving the condition for use in a C<JOIN>,
38 keys using the pseudo-table C<foreign> are resolved to mean "the Table on the
39 other side of the relationship", and values using the pseudo-table C<self>
40 are resolved to mean "the Table this class is representing". Other
41 restrictions, such as by value, sub-select and other tables, may also be
42 used. Please check your database for C<JOIN> parameter support.
44 For example, if you're creating a relationship from C<Author> to C<Book>, where
45 the C<Book> table has a column C<author_id> containing the ID of the C<Author>
48 { 'foreign.author_id' => 'self.id' }
50 will result in the C<JOIN> clause
52 author me JOIN book book ON book.author_id = me.id
54 For multi-column foreign keys, you will need to specify a C<foreign>-to-C<self>
55 mapping for each column in the key. For example, if you're creating a
56 relationship from C<Book> to C<Edition>, where the C<Edition> table refers to a
57 publisher and a type (e.g. "paperback"):
60 'foreign.publisher_id' => 'self.publisher_id',
61 'foreign.type_id' => 'self.type_id',
64 This will result in the C<JOIN> clause:
66 book me JOIN edition edition ON edition.publisher_id = me.publisher_id
67 AND edition.type_id = me.type_id
69 Each key-value pair provided in a hashref will be used as C<AND>ed conditions.
70 To add an C<OR>ed condition, use an arrayref of hashrefs. See the
71 L<SQL::Abstract> documentation for more details.
75 The L<standard ResultSet attributes|DBIx::Class::ResultSet/ATTRIBUTES> may
76 be used as relationship attributes. In particular, the 'where' attribute is
77 useful for filtering relationships:
79 __PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User',
80 { 'foreign.user_id' => 'self.user_id' },
81 { where => { valid => 1 } }
84 The following attributes are also valid:
90 Explicitly specifies the type of join to use in the relationship. Any SQL
91 join type is valid, e.g. C<LEFT> or C<RIGHT>. It will be placed in the SQL
92 command immediately before C<JOIN>.
96 An arrayref containing a list of accessors in the foreign class to create in
97 the main class. If, for example, you do the following:
99 MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes',
101 proxy => [ qw/notes/ ],
104 Then, assuming MyDB::Schema::LinerNotes has an accessor named notes, you can do:
106 my $cd = MyDB::Schema::CD->find(1);
107 $cd->notes('Notes go here'); # set notes -- LinerNotes object is
108 # created if it doesn't exist
112 Specifies the type of accessor that should be created for the relationship.
113 Valid values are C<single> (for when there is only a single related object),
114 C<multi> (when there can be many), and C<filter> (for when there is a single
115 related object, but you also want the relationship accessor to double as
116 a column accessor). For C<multi> accessors, an add_to_* method is also
117 created, which calls C<create_related> for the relationship.
119 =item is_foreign_key_constraint
121 If you are using L<SQL::Translator> to create SQL for you and you find that it
122 is creating constraints where it shouldn't, or not creating them where it
123 should, set this attribute to a true or false value to override the detection
124 of when to create constraints.
128 If C<cascade_copy> is true on a C<has_many> relationship for an
129 object, then when you copy the object all the related objects will
130 be copied too. To turn this behaviour off, pass C<< cascade_copy => 0 >>
131 in the C<$attr> hashref.
133 The behaviour defaults to C<< cascade_copy => 1 >> for C<has_many>
138 By default, DBIx::Class cascades deletes across C<has_many>,
139 C<has_one> and C<might_have> relationships. You can disable this
140 behaviour on a per-relationship basis by supplying
141 C<< cascade_delete => 0 >> in the relationship attributes.
143 The cascaded operations are performed after the requested delete,
144 so if your database has a constraint on the relationship, it will
145 have deleted/updated the related records or raised an exception
146 before DBIx::Class gets to perform the cascaded operation.
150 By default, DBIx::Class cascades updates across C<has_one> and
151 C<might_have> relationships. You can disable this behaviour on a
152 per-relationship basis by supplying C<< cascade_update => 0 >> in
153 the relationship attributes.
155 This is not a RDMS style cascade update - it purely means that when
156 an object has update called on it, all the related objects also
157 have update called. It will not change foreign keys automatically -
158 you must arrange to do this yourself.
160 =item on_delete / on_update
162 If you are using L<SQL::Translator> to create SQL for you, you can use these
163 attributes to explicitly set the desired C<ON DELETE> or C<ON UPDATE> constraint
164 type. If not supplied the SQLT parser will attempt to infer the constraint type by
165 interrogating the attributes of the B<opposite> relationship. For any 'multi'
166 relationship with C<< cascade_delete => 1 >>, the corresponding belongs_to
167 relationship will be created with an C<ON DELETE CASCADE> constraint. For any
168 relationship bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint
169 will be C<ON UPDATE CASCADE>. If you wish to disable this autodetection, and just
170 use the RDBMS' default constraint type, pass C<< on_delete => undef >> or
171 C<< on_delete => '' >>, and the same for C<on_update> respectively.
175 Tells L<SQL::Translator> that the foreign key constraint it creates should be
176 deferrable. In other words, the user may request that the constraint be ignored
177 until the end of the transaction. Currently, only the PostgreSQL producer
178 actually supports this.
182 Tells L<SQL::Translator> to add an index for this constraint. Can also be
183 specified globally in the args to L<DBIx::Class::Schema/deploy> or
184 L<DBIx::Class::Schema/create_ddl_dir>. Default is on, set to 0 to disable.
188 =head2 register_relationship
192 =item Arguments: $relname, $rel_info
196 Registers a relationship on the class. This is called internally by
197 DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
201 sub register_relationship { }
203 =head2 related_resultset
207 =item Arguments: $relationship_name
209 =item Return Value: $related_resultset
213 $rs = $cd->related_resultset('artist');
215 Returns a L<DBIx::Class::ResultSet> for the relationship named
220 sub related_resultset {
222 $self->throw_exception("Can't call *_related as class methods")
225 my $rel_info = $self->relationship_info($rel);
226 $self->throw_exception( "No such relationship ${rel}" )
229 return $self->{related_resultsets}{$rel} ||= do {
230 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
231 $attrs = { %{$rel_info->{attrs} || {}}, %$attrs };
233 $self->throw_exception( "Invalid query: @_" )
234 if (@_ > 1 && (@_ % 2 == 1));
235 my $query = ((@_ > 1) ? {@_} : shift);
237 my $source = $self->result_source;
239 # condition resolution may fail if an incomplete master-object prefetch
240 # is encountered - that is ok during prefetch construction (not yet in_storage)
242 $source->_resolve_condition( $rel_info->{cond}, $rel, $self )
245 if ($self->in_storage) {
246 $self->throw_exception ($_);
249 $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION; # RV
252 if ($cond eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) {
253 my $reverse = $source->reverse_relationship_info($rel);
254 foreach my $rev_rel (keys %$reverse) {
255 if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') {
256 $attrs->{related_objects}{$rev_rel} = [ $self ];
257 Scalar::Util::weaken($attrs->{related_object}{$rev_rel}[0]);
259 $attrs->{related_objects}{$rev_rel} = $self;
260 Scalar::Util::weaken($attrs->{related_object}{$rev_rel});
264 if (ref $cond eq 'ARRAY') {
266 if (ref $_ eq 'HASH') {
268 foreach my $key (keys %$_) {
269 my $newkey = $key !~ /\./ ? "me.$key" : $key;
270 $hash->{$newkey} = $_->{$key};
277 } elsif (ref $cond eq 'HASH') {
278 foreach my $key (grep { ! /\./ } keys %$cond) {
279 $cond->{"me.$key"} = delete $cond->{$key};
282 $query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
283 $self->result_source->related_source($rel)->resultset->search(
289 =head2 search_related
291 @objects = $rs->search_related('relname', $cond, $attrs);
292 $objects_rs = $rs->search_related('relname', $cond, $attrs);
294 Run a search on a related resultset. The search will be restricted to the
295 item or items represented by the L<DBIx::Class::ResultSet> it was called
296 upon. This method can be called on a ResultSet, a Row or a ResultSource class.
301 return shift->related_resultset(shift)->search(@_);
304 =head2 search_related_rs
306 ( $objects_rs ) = $rs->search_related_rs('relname', $cond, $attrs);
308 This method works exactly the same as search_related, except that
309 it guarantees a resultset, even in list context.
313 sub search_related_rs {
314 return shift->related_resultset(shift)->search_rs(@_);
319 $obj->count_related('relname', $cond, $attrs);
321 Returns the count of all the items in the related resultset, restricted by the
322 current item or where conditions. Can be called on a
323 L<DBIx::Class::Manual::Glossary/"ResultSet"> or a
324 L<DBIx::Class::Manual::Glossary/"Row"> object.
330 return $self->search_related(@_)->count;
335 my $new_obj = $obj->new_related('relname', \%col_data);
337 Create a new item of the related foreign class. If called on a
338 L<Row|DBIx::Class::Manual::Glossary/"Row"> object, it will magically
339 set any foreign key columns of the new object to the related primary
340 key columns of the source object for you. The newly created item will
341 not be saved into your storage until you call L<DBIx::Class::Row/insert>
347 my ($self, $rel, $values, $attrs) = @_;
348 return $self->search_related($rel)->new($values, $attrs);
351 =head2 create_related
353 my $new_obj = $obj->create_related('relname', \%col_data);
355 Creates a new item, similarly to new_related, and also inserts the item's data
356 into your storage medium. See the distinction between C<create> and C<new>
357 in L<DBIx::Class::ResultSet> for details.
364 my $obj = $self->search_related($rel)->create(@_);
365 delete $self->{related_resultsets}->{$rel};
371 my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals);
373 Attempt to find a related object using its primary key or unique constraints.
374 See L<DBIx::Class::ResultSet/find> for details.
381 return $self->search_related($rel)->find(@_);
384 =head2 find_or_new_related
386 my $new_obj = $obj->find_or_new_related('relname', \%col_data);
388 Find an item of a related class. If none exists, instantiate a new item of the
389 related class. The object will not be saved into your storage until you call
390 L<DBIx::Class::Row/insert> on it.
394 sub find_or_new_related {
396 my $obj = $self->find_related(@_);
397 return defined $obj ? $obj : $self->new_related(@_);
400 =head2 find_or_create_related
402 my $new_obj = $obj->find_or_create_related('relname', \%col_data);
404 Find or create an item of a related class. See
405 L<DBIx::Class::ResultSet/find_or_create> for details.
409 sub find_or_create_related {
411 my $obj = $self->find_related(@_);
412 return (defined($obj) ? $obj : $self->create_related(@_));
415 =head2 update_or_create_related
417 my $updated_item = $obj->update_or_create_related('relname', \%col_data, \%attrs?);
419 Update or create an item of a related class. See
420 L<DBIx::Class::ResultSet/update_or_create> for details.
424 sub update_or_create_related {
427 return $self->related_resultset($rel)->update_or_create(@_);
430 =head2 set_from_related
432 $book->set_from_related('author', $author_obj);
433 $book->author($author_obj); ## same thing
435 Set column values on the current object, using related values from the given
436 related object. This is used to associate previously separate objects, for
437 example, to set the correct author for a book, find the Author object, then
438 call set_from_related on the book.
440 This is called internally when you pass existing objects as values to
441 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
443 The columns are only set in the local copy of the object, call L</update> to
444 set them in the storage.
448 sub set_from_related {
449 my ($self, $rel, $f_obj) = @_;
450 my $rel_info = $self->relationship_info($rel);
451 $self->throw_exception( "No such relationship ${rel}" ) unless $rel_info;
452 my $cond = $rel_info->{cond};
453 $self->throw_exception(
454 "set_from_related can only handle a hash condition; the ".
455 "condition for $rel is of type ".
456 (ref $cond ? ref $cond : 'plain scalar')
457 ) unless ref $cond eq 'HASH';
458 if (defined $f_obj) {
459 my $f_class = $rel_info->{class};
460 $self->throw_exception( "Object $f_obj isn't a ".$f_class )
461 unless Scalar::Util::blessed($f_obj) and $f_obj->isa($f_class);
464 $self->result_source->_resolve_condition(
465 $rel_info->{cond}, $f_obj, $rel));
469 =head2 update_from_related
471 $book->update_from_related('author', $author_obj);
473 The same as L</"set_from_related">, but the changes are immediately updated
478 sub update_from_related {
480 $self->set_from_related(@_);
484 =head2 delete_related
486 $obj->delete_related('relname', $cond, $attrs);
488 Delete any related item subject to the given conditions.
494 my $obj = $self->search_related(@_)->delete;
495 delete $self->{related_resultsets}->{$_[0]};
501 B<Currently only available for C<has_many>, C<many-to-many> and 'multi' type
506 =item Arguments: ($foreign_vals | $obj), $link_vals?
510 my $role = $schema->resultset('Role')->find(1);
511 $actor->add_to_roles($role);
512 # creates a My::DBIC::Schema::ActorRoles linking table row object
514 $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
515 # creates a new My::DBIC::Schema::Role row object and the linking table
516 # object with an extra column in the link
518 Adds a linking table object for C<$obj> or C<$foreign_vals>. If the first
519 argument is a hash reference, the related object is created first with the
520 column values in the hash. If an object reference is given, just the linking
521 table object is created. In either case, any additional column values for the
522 linking table object can be specified in C<$link_vals>.
526 B<Currently only available for C<many-to-many> relationships.>
530 =item Arguments: (\@hashrefs | \@objs), $link_vals?
534 my $actor = $schema->resultset('Actor')->find(1);
535 my @roles = $schema->resultset('Role')->search({ role =>
536 { '-in' => ['Fred', 'Barney'] } } );
538 $actor->set_roles(\@roles);
539 # Replaces all of $actor's previous roles with the two named
541 $actor->set_roles(\@roles, { salary => 15_000_000 });
542 # Sets a column in the link table for all roles
545 Replace all the related objects with the given reference to a list of
546 objects. This does a C<delete> B<on the link table resultset> to remove the
547 association between the current object and all related objects, then calls
548 C<add_to_$rel> repeatedly to link all the new objects.
550 Note that this means that this method will B<not> delete any objects in the
551 table on the right side of the relation, merely that it will delete the link
554 Due to a mistake in the original implementation of this method, it will also
555 accept a list of objects or hash references. This is B<deprecated> and will be
556 removed in a future version.
558 =head2 remove_from_$rel
560 B<Currently only available for C<many-to-many> relationships.>
564 =item Arguments: $obj
568 my $role = $schema->resultset('Role')->find(1);
569 $actor->remove_from_roles($role);
570 # removes $role's My::DBIC::Schema::ActorRoles linking table row object
572 Removes the link between the current object and the related object. Note that
573 the related object itself won't be deleted unless you call ->delete() on
574 it. This method just removes the link between the two objects.
578 Matt S. Trout <mst@shadowcatsystems.co.uk>
582 You may distribute this code under the same terms as Perl itself.