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.
127 If C<cascade_copy> is true on a C<has_many> relationship for an
128 object, then when you copy the object all the related objects will
129 be copied too. To turn this behaviour off, pass C<< cascade_copy => 0 >>
130 in the C<$attr> hashref.
132 The behaviour defaults to C<< cascade_copy => 1 >> for C<has_many>
137 By default, DBIx::Class cascades deletes across C<has_many>,
138 C<has_one> and C<might_have> relationships. You can disable this
139 behaviour on a per-relationship basis by supplying
140 C<< cascade_delete => 0 >> in the relationship attributes.
142 The cascaded operations are performed after the requested delete,
143 so if your database has a constraint on the relationship, it will
144 have deleted/updated the related records or raised an exception
145 before DBIx::Class gets to perform the cascaded operation.
149 By default, DBIx::Class cascades updates across C<has_one> and
150 C<might_have> relationships. You can disable this behaviour on a
151 per-relationship basis by supplying C<< cascade_update => 0 >> in
152 the relationship attributes.
154 This is not a RDMS style cascade update - it purely means that when
155 an object has update called on it, all the related objects also
156 have update called. It will not change foreign keys automatically -
157 you must arrange to do this yourself.
159 =item on_delete / on_update
161 If you are using L<SQL::Translator> to create SQL for you, you can use these
162 attributes to explicitly set the desired C<ON DELETE> or C<ON UPDATE> constraint
163 type. If not supplied the SQLT parser will attempt to infer the constraint type by
164 interrogating the attributes of the B<opposite> relationship. For any 'multi'
165 relationship with C<< cascade_delete => 1 >>, the corresponding belongs_to
166 relationship will be created with an C<ON DELETE CASCADE> constraint. For any
167 relationship bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint
168 will be C<ON UPDATE CASCADE>. If you wish to disable this autodetection, and just
169 use the RDBMS' default constraint type, pass C<< on_delete => undef >> or
170 C<< on_delete => '' >>, and the same for C<on_update> respectively.
174 Tells L<SQL::Translator> that the foreign key constraint it creates should be
175 deferrable. In other words, the user may request that the constraint be ignored
176 until the end of the transaction. Currently, only the PostgreSQL producer
177 actually supports this.
181 Tells L<SQL::Translator> to add an index for this constraint. Can also be
182 specified globally in the args to L<DBIx::Class::Schema/deploy> or
183 L<DBIx::Class::Schema/create_ddl_dir>. Default is on, set to 0 to disable.
187 =head2 register_relationship
191 =item Arguments: $relname, $rel_info
195 Registers a relationship on the class. This is called internally by
196 DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
200 sub register_relationship { }
202 =head2 related_resultset
206 =item Arguments: $relationship_name
208 =item Return Value: $related_resultset
212 $rs = $cd->related_resultset('artist');
214 Returns a L<DBIx::Class::ResultSet> for the relationship named
219 sub related_resultset {
221 $self->throw_exception("Can't call *_related as class methods")
224 my $rel_info = $self->relationship_info($rel);
225 $self->throw_exception( "No such relationship ${rel}" )
228 return $self->{related_resultsets}{$rel} ||= do {
229 my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
230 $attrs = { %{$rel_info->{attrs} || {}}, %$attrs };
232 $self->throw_exception( "Invalid query: @_" )
233 if (@_ > 1 && (@_ % 2 == 1));
234 my $query = ((@_ > 1) ? {@_} : shift);
236 my $source = $self->result_source;
238 # condition resolution may fail if an incomplete master-object prefetch
239 # is encountered - that is ok during prefetch construction (not yet in_storage)
240 my $cond = eval { $source->_resolve_condition( $rel_info->{cond}, $rel, $self ) };
242 if ($self->in_storage) {
243 $self->throw_exception ($err);
246 $cond = $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION;
250 if ($cond eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) {
251 my $reverse = $source->reverse_relationship_info($rel);
252 foreach my $rev_rel (keys %$reverse) {
253 if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') {
254 $attrs->{related_objects}{$rev_rel} = [ $self ];
255 Scalar::Util::weaken($attrs->{related_object}{$rev_rel}[0]);
257 $attrs->{related_objects}{$rev_rel} = $self;
258 Scalar::Util::weaken($attrs->{related_object}{$rev_rel});
262 if (ref $cond eq 'ARRAY') {
264 if (ref $_ eq 'HASH') {
266 foreach my $key (keys %$_) {
267 my $newkey = $key !~ /\./ ? "me.$key" : $key;
268 $hash->{$newkey} = $_->{$key};
275 } elsif (ref $cond eq 'HASH') {
276 foreach my $key (grep { ! /\./ } keys %$cond) {
277 $cond->{"me.$key"} = delete $cond->{$key};
280 $query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
281 $self->result_source->related_source($rel)->resultset->search(
287 =head2 search_related
289 @objects = $rs->search_related('relname', $cond, $attrs);
290 $objects_rs = $rs->search_related('relname', $cond, $attrs);
292 Run a search on a related resultset. The search will be restricted to the
293 item or items represented by the L<DBIx::Class::ResultSet> it was called
294 upon. This method can be called on a ResultSet, a Row or a ResultSource class.
299 return shift->related_resultset(shift)->search(@_);
302 =head2 search_related_rs
304 ( $objects_rs ) = $rs->search_related_rs('relname', $cond, $attrs);
306 This method works exactly the same as search_related, except that
307 it guarantees a resultset, even in list context.
311 sub search_related_rs {
312 return shift->related_resultset(shift)->search_rs(@_);
317 $obj->count_related('relname', $cond, $attrs);
319 Returns the count of all the items in the related resultset, restricted by the
320 current item or where conditions. Can be called on a
321 L<DBIx::Class::Manual::Glossary/"ResultSet"> or a
322 L<DBIx::Class::Manual::Glossary/"Row"> object.
328 return $self->search_related(@_)->count;
333 my $new_obj = $obj->new_related('relname', \%col_data);
335 Create a new item of the related foreign class. If called on a
336 L<Row|DBIx::Class::Manual::Glossary/"Row"> object, it will magically
337 set any foreign key columns of the new object to the related primary
338 key columns of the source object for you. The newly created item will
339 not be saved into your storage until you call L<DBIx::Class::Row/insert>
345 my ($self, $rel, $values, $attrs) = @_;
346 return $self->search_related($rel)->new($values, $attrs);
349 =head2 create_related
351 my $new_obj = $obj->create_related('relname', \%col_data);
353 Creates a new item, similarly to new_related, and also inserts the item's data
354 into your storage medium. See the distinction between C<create> and C<new>
355 in L<DBIx::Class::ResultSet> for details.
362 my $obj = $self->search_related($rel)->create(@_);
363 delete $self->{related_resultsets}->{$rel};
369 my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals);
371 Attempt to find a related object using its primary key or unique constraints.
372 See L<DBIx::Class::ResultSet/find> for details.
379 return $self->search_related($rel)->find(@_);
382 =head2 find_or_new_related
384 my $new_obj = $obj->find_or_new_related('relname', \%col_data);
386 Find an item of a related class. If none exists, instantiate a new item of the
387 related class. The object will not be saved into your storage until you call
388 L<DBIx::Class::Row/insert> on it.
392 sub find_or_new_related {
394 my $obj = $self->find_related(@_);
395 return defined $obj ? $obj : $self->new_related(@_);
398 =head2 find_or_create_related
400 my $new_obj = $obj->find_or_create_related('relname', \%col_data);
402 Find or create an item of a related class. See
403 L<DBIx::Class::ResultSet/find_or_create> for details.
407 sub find_or_create_related {
409 my $obj = $self->find_related(@_);
410 return (defined($obj) ? $obj : $self->create_related(@_));
413 =head2 update_or_create_related
415 my $updated_item = $obj->update_or_create_related('relname', \%col_data, \%attrs?);
417 Update or create an item of a related class. See
418 L<DBIx::Class::ResultSet/update_or_create> for details.
422 sub update_or_create_related {
425 return $self->related_resultset($rel)->update_or_create(@_);
428 =head2 set_from_related
430 $book->set_from_related('author', $author_obj);
431 $book->author($author_obj); ## same thing
433 Set column values on the current object, using related values from the given
434 related object. This is used to associate previously separate objects, for
435 example, to set the correct author for a book, find the Author object, then
436 call set_from_related on the book.
438 This is called internally when you pass existing objects as values to
439 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
441 The columns are only set in the local copy of the object, call L</update> to
442 set them in the storage.
446 sub set_from_related {
447 my ($self, $rel, $f_obj) = @_;
448 my $rel_info = $self->relationship_info($rel);
449 $self->throw_exception( "No such relationship ${rel}" ) unless $rel_info;
450 my $cond = $rel_info->{cond};
451 $self->throw_exception(
452 "set_from_related can only handle a hash condition; the ".
453 "condition for $rel is of type ".
454 (ref $cond ? ref $cond : 'plain scalar')
455 ) unless ref $cond eq 'HASH';
456 if (defined $f_obj) {
457 my $f_class = $rel_info->{class};
458 $self->throw_exception( "Object $f_obj isn't a ".$f_class )
459 unless Scalar::Util::blessed($f_obj) and $f_obj->isa($f_class);
462 $self->result_source->_resolve_condition(
463 $rel_info->{cond}, $f_obj, $rel));
467 =head2 update_from_related
469 $book->update_from_related('author', $author_obj);
471 The same as L</"set_from_related">, but the changes are immediately updated
476 sub update_from_related {
478 $self->set_from_related(@_);
482 =head2 delete_related
484 $obj->delete_related('relname', $cond, $attrs);
486 Delete any related item subject to the given conditions.
492 my $obj = $self->search_related(@_)->delete;
493 delete $self->{related_resultsets}->{$_[0]};
499 B<Currently only available for C<has_many>, C<many-to-many> and 'multi' type
504 =item Arguments: ($foreign_vals | $obj), $link_vals?
508 my $role = $schema->resultset('Role')->find(1);
509 $actor->add_to_roles($role);
510 # creates a My::DBIC::Schema::ActorRoles linking table row object
512 $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
513 # creates a new My::DBIC::Schema::Role row object and the linking table
514 # object with an extra column in the link
516 Adds a linking table object for C<$obj> or C<$foreign_vals>. If the first
517 argument is a hash reference, the related object is created first with the
518 column values in the hash. If an object reference is given, just the linking
519 table object is created. In either case, any additional column values for the
520 linking table object can be specified in C<$link_vals>.
524 B<Currently only available for C<many-to-many> relationships.>
528 =item Arguments: (\@hashrefs | \@objs), $link_vals?
532 my $actor = $schema->resultset('Actor')->find(1);
533 my @roles = $schema->resultset('Role')->search({ role =>
534 { '-in' => ['Fred', 'Barney'] } } );
536 $actor->set_roles(\@roles);
537 # Replaces all of $actor's previous roles with the two named
539 $actor->set_roles(\@roles, { salary => 15_000_000 });
540 # Sets a column in the link table for all roles
543 Replace all the related objects with the given reference to a list of
544 objects. This does a C<delete> B<on the link table resultset> to remove the
545 association between the current object and all related objects, then calls
546 C<add_to_$rel> repeatedly to link all the new objects.
548 Note that this means that this method will B<not> delete any objects in the
549 table on the right side of the relation, merely that it will delete the link
552 Due to a mistake in the original implementation of this method, it will also
553 accept a list of objects or hash references. This is B<deprecated> and will be
554 removed in a future version.
556 =head2 remove_from_$rel
558 B<Currently only available for C<many-to-many> relationships.>
562 =item Arguments: $obj
566 my $role = $schema->resultset('Role')->find(1);
567 $actor->remove_from_roles($role);
568 # removes $role's My::DBIC::Schema::ActorRoles linking table row object
570 Removes the link between the current object and the related object. Note that
571 the related object itself won't be deleted unless you call ->delete() on
572 it. This method just removes the link between the two objects.
576 Matt S. Trout <mst@shadowcatsystems.co.uk>
580 You may distribute this code under the same terms as Perl itself.