use strict;
use warnings;
-use Scalar::Util ();
use base qw/DBIx::Class/;
+use Scalar::Util qw/weaken blessed/;
+use Try::Tiny;
+use namespace::clean;
+
=head1 NAME
DBIx::Class::Relationship::Base - Inter-table relationships
=head1 SYNOPSIS
+ __PACKAGE__->add_relationship('spiders',
+ 'My::DB::Result::Creatures',
+ sub {
+ my ( $me_alias, $rel_alias) = @_;
+ return
+ { "${rel_alias}.id" => { '=' => \"${me_alias}.id"},
+ "${rel_alias}.type" => { '=', "arachnid" },
+ };
+
+ });
+
=head1 DESCRIPTION
This class provides methods to describe the relationships between the
=over 4
-=item Arguments: 'relname', 'Foreign::Class', $cond, $attrs
+=item Arguments: 'relname', 'Foreign::Class', $condition, $attrs
=back
- __PACKAGE__->add_relationship('relname', 'Foreign::Class', $cond, $attrs);
+ __PACKAGE__->add_relationship('relname',
+ 'Foreign::Class',
+ $condition, $attrs);
+
+Create a custom relationship between one result source and another
+source, indicated by its class name.
-The condition needs to be an L<SQL::Abstract>-style representation of the
-join between the tables. When resolving the condition for use in a C<JOIN>,
-keys using the pseudo-table C<foreign> are resolved to mean "the Table on the
-other side of the relationship", and values using the pseudo-table C<self>
-are resolved to mean "the Table this class is representing". Other
-restrictions, such as by value, sub-select and other tables, may also be
-used. Please check your database for C<JOIN> parameter support.
+=head3 condition
-For example, if you're creating a relationship from C<Author> to C<Book>, where
-the C<Book> table has a column C<author_id> containing the ID of the C<Author>
-row:
+The condition argument describes the JOIN expression used to connect
+the two sources when creating SQL queries.
+
+To create simple equality joins, supply a hashref containing the
+remote table column name as the key(s), and the local table column
+name as the value(s), for example:
{ 'foreign.author_id' => 'self.id' }
-will result in the C<JOIN> clause
+will result in the C<JOIN> clause:
author me JOIN book book ON book.author_id = me.id
-For multi-column foreign keys, you will need to specify a C<foreign>-to-C<self>
-mapping for each column in the key. For example, if you're creating a
-relationship from C<Book> to C<Edition>, where the C<Edition> table refers to a
-publisher and a type (e.g. "paperback"):
+This describes a relationship between the C<Author> table and the
+C<Book> table where the C<Book> table has a column C<author_id>
+containing the ID value of the C<Author>.
+
+C<foreign> and C<self> are psuedo aliases and must be entered
+literally. They will be replaced with the actual correct table alias
+when the SQL is produced.
+
+Similarly:
{
'foreign.publisher_id' => 'self.publisher_id',
'foreign.type_id' => 'self.type_id',
}
-This will result in the C<JOIN> clause:
+will result in the C<JOIN> clause:
book me JOIN edition edition ON edition.publisher_id = me.publisher_id
AND edition.type_id = me.type_id
-Each key-value pair provided in a hashref will be used as C<AND>ed conditions.
-To add an C<OR>ed condition, use an arrayref of hashrefs. See the
-L<SQL::Abstract> documentation for more details.
+This describes the relationship from C<Book> to C<Edition>, where the
+C<Edition> table refers to a publisher and a type (e.g. "paperback"):
+
+As is the default in L<SQL::Abstract>, the key-value pairs will be
+C<AND>ed in the result. C<OR> can be achieved with an arrayref, for
+example:
+
+ [
+ { 'foreign.left_itemid' => 'self.id' },
+ { 'foreign.right_itemid' => 'self.id' },
+ ]
+
+which results in the C<JOIN> clause:
+
+ items me JOIN related_items rel_link ON rel_link.left_itemid = me.id
+ OR rel_link.right_itemid = me.id
+
+This describes the relationship from C<Items> to C<RelatedItems>,
+where C<RelatedItems> is a many-to-many linking table, linking Items
+back to themselves.
+
+To create joins which describe more than a simple equality of column
+values, the custom join condition coderef syntax can be used:
+
+ sub {
+ my ( $me_alias, $rel_alias ) = @_;
+ return
+ ({ "${rel_alias}.artist" => { '=' => \"${me_alias}.artistid"},
+ "${rel_alias}.year" => { '>', "1979",
+ '<', "1990" }
+ });
+ }
+
+this will result in the C<JOIN> clause:
+
+ artist me LEFT JOIN cd cds_80s_noopt ON
+ ( cds_80s_noopt.artist = me.artistid
+ AND ( cds_80s_noopt.year < ? AND cds_80s_noopt.year > ? )
+ )
+
+with the bind values:
+
+ '1990', '1979'
+
+C<$rel_alias> is the equivalent to C<foreign> in the simple syntax,
+and will be replaced by the actual remote table alias in the produced
+SQL. Similarly, C<$me_alias> is the equivalent to C<self> and will be
+replaced with the local table alias in the SQL.
+
+The actual syntax returned by the coderef should be valid
+L<SQL::Abstract> syntax, similar to normal
+L<DBIx::Class::ResultSet/search> conditions.
+
+To help optimise the SQL produced, a second optional hashref can be
+returned to be used when the relationship accessor is called directly
+on a Row object:
+
+ sub {
+ my ( $me_alias, $rel_alias, $me_result_source,
+ $rel_name, $optional_me_object ) = @_;
+ return
+ ({ "${rel_alias}.artist" => { '=' => \"${me_alias}.artistid"},
+ "${rel_alias}.year" => { '>', "1979",
+ '<', "1990" }
+ },
+ $optional_me_object &&
+ { "${rel_alias}.artist" => $optional_me_object->artistid,
+ "${rel_alias}.year" => { '>', "1979",
+ '<', "1990" }
+ });
+ }
+
+Now this code:
+
+ my $artist = $schema->resultset("Artist")->find({ id => 4 });
+ $artist->cds_80s->all;
+
+Produces:
+
+ SELECT me.cdid, me.artist, me.title, me.year, me.genreid, me.single_track
+ FROM cd me
+ WHERE ( ( me.artist = ? AND ( me.year < ? AND me.year > ? ) ) )
-In addition to standard result set attributes, the following attributes are also valid:
+With the bind values:
+
+ '4', '1990', '1979'
+
+The C<$optional_me_object> used to create the second hashref contains
+a row object, the object that the relation accessor was called on.
+
+C<$me_result_source> the L<DBIx::Class::ResultSource> of the table
+being searched on, and C<$rel_name>, the name of the relation
+containing this condition, are also provided as arguments. These may
+be useful to more complicated condition calculation.
+
+=head3 attributes
+
+The L<standard ResultSet attributes|DBIx::Class::ResultSet/ATTRIBUTES> may
+be used as relationship attributes. In particular, the 'where' attribute is
+useful for filtering relationships:
+
+ __PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User',
+ { 'foreign.user_id' => 'self.user_id' },
+ { where => { valid => 1 } }
+ );
+
+The following attributes are also valid:
=over 4
join type is valid, e.g. C<LEFT> or C<RIGHT>. It will be placed in the SQL
command immediately before C<JOIN>.
-=item proxy
+=item proxy =E<gt> $column | \@columns | \%column
+
+=over 4
+
+=item \@columns
An arrayref containing a list of accessors in the foreign class to create in
the main class. If, for example, you do the following:
-
+
MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes',
undef, {
proxy => [ qw/notes/ ],
});
-
+
Then, assuming MyDB::Schema::LinerNotes has an accessor named notes, you can do:
my $cd = MyDB::Schema::CD->find(1);
$cd->notes('Notes go here'); # set notes -- LinerNotes object is
# created if it doesn't exist
-
+
+=item \%column
+
+A hashref where each key is the accessor you want installed in the main class,
+and its value is the name of the original in the fireign class.
+
+ MyDB::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd', {
+ proxy => { cd_title => 'title' },
+ });
+
+This will create an accessor named C<cd_title> on the C<$track> row object.
+
+=back
+
+NOTE: you can pass a nested struct too, for example:
+
+ MyDB::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd', {
+ proxy => [ 'year', { cd_title => 'title' } ],
+ });
+
=item accessor
Specifies the type of accessor that should be created for the relationship.
=item is_foreign_key_constraint
If you are using L<SQL::Translator> to create SQL for you and you find that it
-is creating constraints where it shouldn't, or not creating them where it
+is creating constraints where it shouldn't, or not creating them where it
should, set this attribute to a true or false value to override the detection
of when to create constraints.
+=item cascade_copy
+
+If C<cascade_copy> is true on a C<has_many> relationship for an
+object, then when you copy the object all the related objects will
+be copied too. To turn this behaviour off, pass C<< cascade_copy => 0 >>
+in the C<$attr> hashref.
+
+The behaviour defaults to C<< cascade_copy => 1 >> for C<has_many>
+relationships.
+
+=item cascade_delete
+
+By default, DBIx::Class cascades deletes across C<has_many>,
+C<has_one> and C<might_have> relationships. You can disable this
+behaviour on a per-relationship basis by supplying
+C<< cascade_delete => 0 >> in the relationship attributes.
+
+The cascaded operations are performed after the requested delete,
+so if your database has a constraint on the relationship, it will
+have deleted/updated the related records or raised an exception
+before DBIx::Class gets to perform the cascaded operation.
+
+=item cascade_update
+
+By default, DBIx::Class cascades updates across C<has_one> and
+C<might_have> relationships. You can disable this behaviour on a
+per-relationship basis by supplying C<< cascade_update => 0 >> in
+the relationship attributes.
+
+This is not a RDMS style cascade update - it purely means that when
+an object has update called on it, all the related objects also
+have update called. It will not change foreign keys automatically -
+you must arrange to do this yourself.
+
+=item on_delete / on_update
+
+If you are using L<SQL::Translator> to create SQL for you, you can use these
+attributes to explicitly set the desired C<ON DELETE> or C<ON UPDATE> constraint
+type. If not supplied the SQLT parser will attempt to infer the constraint type by
+interrogating the attributes of the B<opposite> relationship. For any 'multi'
+relationship with C<< cascade_delete => 1 >>, the corresponding belongs_to
+relationship will be created with an C<ON DELETE CASCADE> constraint. For any
+relationship bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint
+will be C<ON UPDATE CASCADE>. If you wish to disable this autodetection, and just
+use the RDBMS' default constraint type, pass C<< on_delete => undef >> or
+C<< on_delete => '' >>, and the same for C<on_update> respectively.
+
=item is_deferrable
Tells L<SQL::Translator> that the foreign key constraint it creates should be
until the end of the transaction. Currently, only the PostgreSQL producer
actually supports this.
+=item add_fk_index
+
+Tells L<SQL::Translator> to add an index for this constraint. Can also be
+specified globally in the args to L<DBIx::Class::Schema/deploy> or
+L<DBIx::Class::Schema/create_ddl_dir>. Default is on, set to 0 to disable.
+
=back
=head2 register_relationship
$self->throw_exception("Can't call *_related as class methods")
unless ref $self;
my $rel = shift;
- my $rel_obj = $self->relationship_info($rel);
+ my $rel_info = $self->relationship_info($rel);
$self->throw_exception( "No such relationship ${rel}" )
- unless $rel_obj;
-
+ unless $rel_info;
+
return $self->{related_resultsets}{$rel} ||= do {
my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
- $attrs = { %{$rel_obj->{attrs} || {}}, %$attrs };
+ $attrs = { %{$rel_info->{attrs} || {}}, %$attrs };
$self->throw_exception( "Invalid query: @_" )
if (@_ > 1 && (@_ % 2 == 1));
my $query = ((@_ > 1) ? {@_} : shift);
- my $cond = $self->result_source->resolve_condition(
- $rel_obj->{cond}, $rel, $self
- );
+ my $source = $self->result_source;
+
+ # condition resolution may fail if an incomplete master-object prefetch
+ # is encountered - that is ok during prefetch construction (not yet in_storage)
+
+ # if $rel_info->{cond} is a CODE, we might need to join from the
+ # current resultsource instead of just querying the target
+ # resultsource, in that case, the condition might provide an
+ # additional condition in order to avoid an unecessary join if
+ # that is at all possible.
+ my ($cond, $extended_cond) = try {
+ $source->_resolve_condition( $rel_info->{cond}, $rel, $self )
+ }
+ catch {
+ if ($self->in_storage) {
+ $self->throw_exception ($_);
+ }
+
+ $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION; # RV
+ };
+
+ if ($cond eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) {
+ my $reverse = $source->reverse_relationship_info($rel);
+ foreach my $rev_rel (keys %$reverse) {
+ if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') {
+ $attrs->{related_objects}{$rev_rel} = [ $self ];
+ weaken $attrs->{related_object}{$rev_rel}[0];
+ } else {
+ $attrs->{related_objects}{$rev_rel} = $self;
+ weaken $attrs->{related_object}{$rev_rel};
+ }
+ }
+ }
+
+ # this is where we're going to check if we have an extended
+ # rel. In that case, we need to: 1) If there's a second
+ # condition, we use that instead. 2) If there is only one
+ # condition, we need to join the current resultsource and have
+ # additional conditions.
+ if (ref $rel_info->{cond} eq 'CODE') {
+ # this is an extended relationship.
+ if ($extended_cond) {
+ $cond = $extended_cond;
+
+ } else {
+
+ # it's a bit hard to find out what to do with other joins
+ $self->throw_exception('Extended relationship '.$rel.' with additional join requires optimized declaration')
+ if exists $attrs->{join} && $attrs->{join};
+
+ # aliases get a bit more complicated, so we won't accept additional queries
+ $self->throw_exception('Extended relationship '.$rel.' with additional query requires optimized declaration')
+ if $query;
+
+ $attrs->{from} =
+ [ { $rel => $self->result_source->from },
+ [ { 'me' => $self->result_source->related_source($rel)->from }, { 1 => 1 } ] ];
+
+ $cond->{"${rel}.${_}"} = $self->get_column($_) for $self->result_source->primary_columns;
+ }
+ }
+
if (ref $cond eq 'ARRAY') {
- $cond = [ map { my $hash;
- foreach my $key (keys %$_) {
- my $newkey = $key =~ /\./ ? "me.$key" : $key;
- $hash->{$newkey} = $_->{$key};
- }; $hash } @$cond ];
- } else {
+ $cond = [ map {
+ if (ref $_ eq 'HASH') {
+ my $hash;
+ foreach my $key (keys %$_) {
+ my $newkey = $key !~ /\./ ? "me.$key" : $key;
+ $hash->{$newkey} = $_->{$key};
+ }
+ $hash;
+ } else {
+ $_;
+ }
+ } @$cond ];
+ } elsif (ref $cond eq 'HASH') {
foreach my $key (grep { ! /\./ } keys %$cond) {
$cond->{"me.$key"} = delete $cond->{$key};
}
}
+
$query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
$self->result_source->related_source($rel)->resultset->search(
$query, $attrs
( $objects_rs ) = $rs->search_related_rs('relname', $cond, $attrs);
-This method works exactly the same as search_related, except that
-it garauntees a restultset, even in list context.
+This method works exactly the same as search_related, except that
+it guarantees a resultset, even in list context.
=cut
my $new_obj = $obj->new_related('relname', \%col_data);
Create a new item of the related foreign class. If called on a
-L<Row|DBIx::Class::Manual::Glossary/"Row"> object, it will magically
-set any foreign key columns of the new object to the related primary
-key columns of the source object for you. The newly created item will
+L<Row|DBIx::Class::Manual::Glossary/"Row"> object, it will magically
+set any foreign key columns of the new object to the related primary
+key columns of the source object for you. The newly created item will
not be saved into your storage until you call L<DBIx::Class::Row/insert>
on it.
call set_from_related on the book.
This is called internally when you pass existing objects as values to
-L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to acessor.
+L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
The columns are only set in the local copy of the object, call L</update> to
set them in the storage.
sub set_from_related {
my ($self, $rel, $f_obj) = @_;
- my $rel_obj = $self->relationship_info($rel);
- $self->throw_exception( "No such relationship ${rel}" ) unless $rel_obj;
- my $cond = $rel_obj->{cond};
+ my $rel_info = $self->relationship_info($rel);
+ $self->throw_exception( "No such relationship ${rel}" ) unless $rel_info;
+ my $cond = $rel_info->{cond};
$self->throw_exception(
"set_from_related can only handle a hash condition; the ".
"condition for $rel is of type ".
(ref $cond ? ref $cond : 'plain scalar')
) unless ref $cond eq 'HASH';
if (defined $f_obj) {
- my $f_class = $self->result_source->schema->class($rel_obj->{class});
+ my $f_class = $rel_info->{class};
$self->throw_exception( "Object $f_obj isn't a ".$f_class )
- unless Scalar::Util::blessed($f_obj) and $f_obj->isa($f_class);
+ unless blessed $f_obj and $f_obj->isa($f_class);
}
- $self->set_columns(
- $self->result_source->resolve_condition(
- $rel_obj->{cond}, $f_obj, $rel));
+
+ # _resolve_condition might return two hashrefs, specially in the
+ # current case, since we know $f_object is an object.
+ my ($condref1, $condref2) = $self->result_source->_resolve_condition
+ ($rel_info->{cond}, $f_obj, $rel);
+
+ # if we get two condrefs, we need to use the second, otherwise we
+ # use the first.
+ $self->set_columns($condref2 ? $condref2 : $condref1);
+
return 1;
}
=over 4
-=item Arguments: (\@hashrefs | \@objs)
+=item Arguments: (\@hashrefs | \@objs), $link_vals?
=back
my $actor = $schema->resultset('Actor')->find(1);
- my @roles = $schema->resultset('Role')->search({ role =>
- { '-in' -> ['Fred', 'Barney'] } } );
+ my @roles = $schema->resultset('Role')->search({ role =>
+ { '-in' => ['Fred', 'Barney'] } } );
$actor->set_roles(\@roles);
# Replaces all of $actor's previous roles with the two named
+ $actor->set_roles(\@roles, { salary => 15_000_000 });
+ # Sets a column in the link table for all roles
+
+
Replace all the related objects with the given reference to a list of
objects. This does a C<delete> B<on the link table resultset> to remove the
association between the current object and all related objects, then calls
projects / dbsrgits/DBIx-Class.git / blobdiff