.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DBIx::Class::Relationship::Base 3pm"
.TH DBIx::Class::Relationship::Base 3pm "2022-05-21" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBIx::Class::Relationship::Base \- Inter\-table relationships
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&  _\|_PACKAGE_\|_\->add_relationship(
\&    spiders => \*(AqMy::DB::Result::Creatures\*(Aq,
\&    sub {
\&      my $args = shift;
\&      return {
\&        "$args\->{foreign_alias}.id"   => { \-ident => "$args\->{self_alias}.id" },
\&        "$args\->{foreign_alias}.type" => \*(Aqarachnid\*(Aq
\&      };
\&    },
\&  );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class provides methods to describe the relationships between the
tables in your database model. These are the \*(L"bare bones\*(R" relationships
methods, for predefined ones, look in DBIx::Class::Relationship.
.SH "METHODS"
.IX Header "METHODS"
.SS "add_relationship"
.IX Subsection "add_relationship"
.ie n .IP "Arguments: $rel_name, $foreign_class, $condition, $attrs" 4
.el .IP "Arguments: \f(CW$rel_name\fR, \f(CW$foreign_class\fR, \f(CW$condition\fR, \f(CW$attrs\fR" 4
.IX Item "Arguments: $rel_name, $foreign_class, $condition, $attrs"
.PP
.Vb 3
\&  _\|_PACKAGE_\|_\->add_relationship(\*(Aqrel_name\*(Aq,
\&                                \*(AqForeign::Class\*(Aq,
\&                                $condition, $attrs);
.Ve
.PP
Create a custom relationship between one result source and another
source, indicated by its class name.
.PP
\fIcondition\fR
.IX Subsection "condition"
.PP
The condition argument describes the \f(CW\*(C`ON\*(C'\fR clause of the \f(CW\*(C`JOIN\*(C'\fR
expression used to connect the two sources when creating \s-1SQL\s0 queries.
.PP
Simple equality
.IX Subsection "Simple equality"
.PP
To create simple equality joins, supply a hashref containing the remote
table column name as the key(s) prefixed by \f(CW\*(Aqforeign.\*(Aq\fR, and the
corresponding local table column name as the value(s) prefixed by \f(CW\*(Aqself.\*(Aq\fR.
Both \f(CW\*(C`foreign\*(C'\fR and \f(CW\*(C`self\*(C'\fR are pseudo aliases and must be entered
literally. They will be replaced with the actual correct table alias
when the \s-1SQL\s0 is produced.
.PP
For example given:
.PP
.Vb 4
\&  My::Schema::Author\->has_many(
\&    books => \*(AqMy::Schema::Book\*(Aq,
\&    { \*(Aqforeign.author_id\*(Aq => \*(Aqself.id\*(Aq }
\&  );
.Ve
.PP
A query like:
.PP
.Vb 1
\&  $author_rs\->search_related(\*(Aqbooks\*(Aq)\->next
.Ve
.PP
will result in the following \f(CW\*(C`JOIN\*(C'\fR clause:
.PP
.Vb 1
\&  ... FROM author me LEFT JOIN book books ON books.author_id = me.id ...
.Ve
.PP
This describes a relationship between the \f(CW\*(C`Author\*(C'\fR table and the
\&\f(CW\*(C`Book\*(C'\fR table where the \f(CW\*(C`Book\*(C'\fR table has a column \f(CW\*(C`author_id\*(C'\fR
containing the \s-1ID\s0 value of the \f(CW\*(C`Author\*(C'\fR.
.PP
Similarly:
.PP
.Vb 7
\&  My::Schema::Book\->has_many(
\&    editions => \*(AqMy::Schema::Edition\*(Aq,
\&    {
\&      \*(Aqforeign.publisher_id\*(Aq => \*(Aqself.publisher_id\*(Aq,
\&      \*(Aqforeign.type_id\*(Aq      => \*(Aqself.type_id\*(Aq,
\&    }
\&  );
\&
\&  ...
\&
\&  $book_rs\->search_related(\*(Aqeditions\*(Aq)\->next
.Ve
.PP
will result in the \f(CW\*(C`JOIN\*(C'\fR clause:
.PP
.Vb 4
\&  ... FROM book me
\&      LEFT JOIN edition editions ON
\&           editions.publisher_id = me.publisher_id
\&       AND editions.type_id = me.type_id ...
.Ve
.PP
This describes the relationship from \f(CW\*(C`Book\*(C'\fR to \f(CW\*(C`Edition\*(C'\fR, where the
\&\f(CW\*(C`Edition\*(C'\fR table refers to a publisher and a type (e.g. \*(L"paperback\*(R"):
.PP
Multiple groups of simple equality conditions
.IX Subsection "Multiple groups of simple equality conditions"
.PP
As is the default in SQL::Abstract::Classic, the key-value pairs will be
\&\f(CW\*(C`AND\*(C'\fRed in the resulting \f(CW\*(C`JOIN\*(C'\fR clause. An \f(CW\*(C`OR\*(C'\fR can be achieved with
an arrayref. For example a condition like:
.PP
.Vb 7
\&  My::Schema::Item\->has_many(
\&    related_item_links => My::Schema::Item::Links,
\&    [
\&      { \*(Aqforeign.left_itemid\*(Aq  => \*(Aqself.id\*(Aq },
\&      { \*(Aqforeign.right_itemid\*(Aq => \*(Aqself.id\*(Aq },
\&    ],
\&  );
.Ve
.PP
will translate to the following \f(CW\*(C`JOIN\*(C'\fR clause:
.PP
.Vb 3
\& ... FROM item me JOIN item_relations related_item_links ON
\&         related_item_links.left_itemid = me.id
\&      OR related_item_links.right_itemid = me.id ...
.Ve
.PP
This describes the relationship from \f(CW\*(C`Item\*(C'\fR to \f(CW\*(C`Item::Links\*(C'\fR, where
\&\f(CW\*(C`Item::Links\*(C'\fR is a many-to-many linking table, linking items back to
themselves in a peer fashion (without a \*(L"parent-child\*(R" designation)
.PP
Custom join conditions
.IX Subsection "Custom join conditions"
.PP
.Vb 5
\&  NOTE: The custom join condition specification mechanism is capable of
\&  generating JOIN clauses of virtually unlimited complexity. This may limit
\&  your ability to traverse some of the more involved relationship chains the
\&  way you expect, *and* may bring your RDBMS to its knees. Exercise care
\&  when declaring relationships as described here.
.Ve
.PP
To specify joins which describe more than a simple equality of column
values, the custom join condition coderef syntax can be used. For
example:
.PP
.Vb 4
\&  My::Schema::Artist\->has_many(
\&    cds_80s => \*(AqMy::Schema::CD\*(Aq,
\&    sub {
\&      my $args = shift;
\&
\&      return {
\&        "$args\->{foreign_alias}.artist" => { \-ident => "$args\->{self_alias}.artistid" },
\&        "$args\->{foreign_alias}.year"   => { \*(Aq>\*(Aq, "1979", \*(Aq<\*(Aq, "1990" },
\&      };
\&    }
\&  );
\&
\&  ...
\&
\&  $artist_rs\->search_related(\*(Aqcds_80s\*(Aq)\->next;
.Ve
.PP
will result in the \f(CW\*(C`JOIN\*(C'\fR clause:
.PP
.Vb 4
\&  ... FROM artist me LEFT JOIN cd cds_80s ON
\&        cds_80s.artist = me.artistid
\&    AND cds_80s.year < ?
\&    AND cds_80s.year > ?
.Ve
.PP
with the bind values:
.PP
.Vb 1
\&   \*(Aq1990\*(Aq, \*(Aq1979\*(Aq
.Ve
.PP
\&\f(CW\*(C`$args\->{foreign_alias}\*(C'\fR and \f(CW\*(C`$args\->{self_alias}\*(C'\fR are supplied the
same values that would be otherwise substituted for \f(CW\*(C`foreign\*(C'\fR and \f(CW\*(C`self\*(C'\fR
in the simple hashref syntax case.
.PP
The coderef is expected to return a valid SQL::Abstract::Classic
query-structure, just like what one would supply as the first argument to
\&\*(L"search\*(R" in DBIx::Class::ResultSet. The return value will be passed directly to
DBIx::Class::SQLMaker and the resulting \s-1SQL\s0 will be used verbatim as the
\&\f(CW\*(C`ON\*(C'\fR clause of the \f(CW\*(C`JOIN\*(C'\fR statement associated with this relationship.
.PP
While every coderef-based condition must return a valid \f(CW\*(C`ON\*(C'\fR clause, it may
elect to additionally return a simplified \fBoptional\fR join-free condition
consisting of a hashref with \fBall keys being fully qualified names of columns
declared on the corresponding result source\fR. This boils down to two scenarios:
.IP "\(bu" 4
When relationship resolution is invoked after \f(CW\*(C`$result\->$rel_name\*(C'\fR, as
opposed to \f(CW\*(C`$rs\->related_resultset($rel_name)\*(C'\fR, the \f(CW$result\fR object
is passed to the coderef as \f(CW\*(C`$args\->{self_result_object}\*(C'\fR.
.IP "\(bu" 4
Alternatively when the user-space invokes resolution via
\&\f(CW\*(C`$result\->set_from_related( $rel_name => $foreign_values_or_object )\*(C'\fR, the
corresponding data is passed to the coderef as \f(CW\*(C`$args\->{foreign_values}\*(C'\fR,
\&\fBalways\fR in the form of a hashref. If a foreign result object is supplied
(which is valid usage of \*(L"set_from_related\*(R"), its values will be extracted
into hashref form by calling get_columns.
.PP
Note that the above scenarios are mutually exclusive, that is you will be supplied
none or only one of \f(CW\*(C`self_result_object\*(C'\fR and \f(CW\*(C`foreign_values\*(C'\fR. In other words if
you define your condition coderef as:
.PP
.Vb 2
\&  sub {
\&    my $args = shift;
\&
\&    return (
\&      {
\&        "$args\->{foreign_alias}.artist" => { \-ident => "$args\->{self_alias}.artistid" },
\&        "$args\->{foreign_alias}.year"   => { \*(Aq>\*(Aq, "1979", \*(Aq<\*(Aq, "1990" },
\&      },
\&      ! $args\->{self_result_object} ? () : {
\&        "$args\->{foreign_alias}.artist" => $args\->{self_result_object}\->artistid,
\&        "$args\->{foreign_alias}.year"   => { \*(Aq>\*(Aq, "1979", \*(Aq<\*(Aq, "1990" },
\&      },
\&      ! $args\->{foreign_values} ? () : {
\&        "$args\->{self_alias}.artistid" => $args\->{foreign_values}{artist},
\&      }
\&    );
\&  }
.Ve
.PP
Then this code:
.PP
.Vb 2
\&    my $artist = $schema\->resultset("Artist")\->find({ id => 4 });
\&    $artist\->cds_80s\->all;
.Ve
.PP
Can skip a \f(CW\*(C`JOIN\*(C'\fR altogether and instead produce:
.PP
.Vb 5
\&    SELECT cds_80s.cdid, cds_80s.artist, cds_80s.title, cds_80s.year, cds_80s.genreid, cds_80s.single_track
\&      FROM cd cds_80s
\&      WHERE cds_80s.artist = ?
\&        AND cds_80s.year < ?
\&        AND cds_80s.year > ?
.Ve
.PP
With the bind values:
.PP
.Vb 1
\&    \*(Aq4\*(Aq, \*(Aq1990\*(Aq, \*(Aq1979\*(Aq
.Ve
.PP
While this code:
.PP
.Vb 3
\&    my $cd = $schema\->resultset("CD")\->search({ artist => 1 }, { rows => 1 })\->single;
\&    my $artist = $schema\->resultset("Artist")\->new({});
\&    $artist\->set_from_related(\*(Aqcds_80s\*(Aq);
.Ve
.PP
Will properly set the \f(CW\*(C`$artist\->artistid\*(C'\fR field of this new object to \f(CW1\fR
.PP
Note that in order to be able to use \*(L"set_from_related\*(R" (and by extension
\&\f(CW$result\fR\->create_related),
the returned join free condition \fBmust\fR contain only plain values/deflatable
objects. For instance the \f(CW\*(C`year\*(C'\fR constraint in the above example prevents
the relationship from being used to create related objects using
\&\f(CW\*(C`$artst\->create_related( cds_80s => { title => \*(Aqblah\*(Aq } )\*(C'\fR (an
exception will be thrown).
.PP
In order to allow the user to go truly crazy when generating a custom \f(CW\*(C`ON\*(C'\fR
clause, the \f(CW$args\fR hashref passed to the subroutine contains some extra
metadata. Currently the supplied coderef is executed as:
.PP
.Vb 3
\&  $relationship_info\->{cond}\->({
\&    self_resultsource   => The resultsource instance on which rel_name is registered
\&    rel_name            => The relationship name (does *NOT* always match foreign_alias)
\&
\&    self_alias          => The alias of the invoking resultset
\&    foreign_alias       => The alias of the to\-be\-joined resultset (does *NOT* always match rel_name)
\&
\&    # only one of these (or none at all) will ever be supplied to aid in the
\&    # construction of a join\-free condition
\&
\&    self_result_object  => The invocant *object* itself in case of a call like
\&                           $result_object\->$rel_name( ... )
\&
\&    foreign_values      => A *hashref* of related data: may be passed in directly or
\&                           derived via \->get_columns() from a related object in case of
\&                           $result_object\->set_from_related( $rel_name, $foreign_result_object )
\&
\&    # deprecated inconsistent names, will be forever available for legacy code
\&    self_rowobj         => Old deprecated slot for self_result_object
\&    foreign_relname     => Old deprecated slot for rel_name
\&  });
.Ve
.PP
\fIattributes\fR
.IX Subsection "attributes"
.PP
The standard ResultSet attributes may
be used as relationship attributes. In particular, the 'where' attribute is
useful for filtering relationships:
.PP
.Vb 4
\&     _\|_PACKAGE_\|_\->has_many( \*(Aqvalid_users\*(Aq, \*(AqMyApp::Schema::User\*(Aq,
\&        { \*(Aqforeign.user_id\*(Aq => \*(Aqself.user_id\*(Aq },
\&        { where => { valid => 1 } }
\&    );
.Ve
.PP
The following attributes are also valid:
.IP "join_type" 4
.IX Item "join_type"
Explicitly specifies the type of join to use in the relationship. Any \s-1SQL\s0
join type is valid, e.g. \f(CW\*(C`LEFT\*(C'\fR or \f(CW\*(C`RIGHT\*(C'\fR. It will be placed in the \s-1SQL\s0
command immediately before \f(CW\*(C`JOIN\*(C'\fR.
.ie n .IP "proxy => $column | \e@columns | \e%column" 4
.el .IP "proxy => \f(CW$column\fR | \e@columns | \e%column" 4
.IX Item "proxy => $column | @columns | %column"
The 'proxy' attribute can be used to retrieve values, and to perform
updates if the relationship has 'cascade_update' set. The 'might_have'
and 'has_one' relationships have this set by default; if you want a proxy
to update across a 'belongs_to' relationship, you must set the attribute
yourself.
.RS 4
.IP "\e@columns" 4
.IX 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:
.Sp
.Vb 4
\&  MyApp::Schema::CD\->might_have(liner_notes => \*(AqMyApp::Schema::LinerNotes\*(Aq,
\&    undef, {
\&      proxy => [ qw/notes/ ],
\&    });
.Ve
.Sp
Then, assuming MyApp::Schema::LinerNotes has an accessor named notes, you can do:
.Sp
.Vb 3
\&  my $cd = MyApp::Schema::CD\->find(1);
\&  $cd\->notes(\*(AqNotes go here\*(Aq); # set notes \-\- LinerNotes object is
\&                               # created if it doesn\*(Aqt exist
.Ve
.Sp
For a 'belongs_to relationship, note the 'cascade_update':
.Sp
.Vb 5
\&  MyApp::Schema::Track\->belongs_to( cd => \*(AqMyApp::Schema::CD\*(Aq, \*(Aqcd,
\&      { proxy => [\*(Aqtitle\*(Aq], cascade_update => 1 }
\&  );
\&  $track\->title(\*(AqNew Title\*(Aq);
\&  $track\->update; # updates title in CD
.Ve
.IP "\e%column" 4
.IX 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 foreign class.
.Sp
.Vb 3
\&  MyApp::Schema::Track\->belongs_to( cd => \*(AqMyApp::Schema::CD\*(Aq, \*(Aqcd\*(Aq, {
\&      proxy => { cd_title => \*(Aqtitle\*(Aq },
\&  });
.Ve
.Sp
This will create an accessor named \f(CW\*(C`cd_title\*(C'\fR on the \f(CW$track\fR result object.
.RE
.RS 4
.Sp
\&\s-1NOTE:\s0 you can pass a nested struct too, for example:
.Sp
.Vb 3
\&  MyApp::Schema::Track\->belongs_to( cd => \*(AqMyApp::Schema::CD\*(Aq, \*(Aqcd\*(Aq, {
\&    proxy => [ \*(Aqyear\*(Aq, { cd_title => \*(Aqtitle\*(Aq } ],
\&  });
.Ve
.RE
.IP "accessor" 4
.IX Item "accessor"
Specifies the type of accessor that should be created for the relationship.
Valid values are \f(CW\*(C`single\*(C'\fR (for when there is only a single related object),
\&\f(CW\*(C`multi\*(C'\fR (when there can be many), and \f(CW\*(C`filter\*(C'\fR (for when there is a single
related object, but you also want the relationship accessor to double as
a column accessor). For \f(CW\*(C`multi\*(C'\fR accessors, an add_to_* method is also
created, which calls \f(CW\*(C`create_related\*(C'\fR for the relationship.
.IP "is_foreign_key_constraint" 4
.IX Item "is_foreign_key_constraint"
If you are using SQL::Translator to create \s-1SQL\s0 for you and you find that 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.
.IP "cascade_copy" 4
.IX Item "cascade_copy"
If \f(CW\*(C`cascade_copy\*(C'\fR is true on a \f(CW\*(C`has_many\*(C'\fR relationship for an
object, then when you copy the object all the related objects will
be copied too. To turn this behaviour off, pass \f(CW\*(C`cascade_copy => 0\*(C'\fR
in the \f(CW$attr\fR hashref.
.Sp
The behaviour defaults to \f(CW\*(C`cascade_copy => 1\*(C'\fR for \f(CW\*(C`has_many\*(C'\fR
relationships.
.IP "cascade_delete" 4
.IX Item "cascade_delete"
By default, DBIx::Class cascades deletes across \f(CW\*(C`has_many\*(C'\fR,
\&\f(CW\*(C`has_one\*(C'\fR and \f(CW\*(C`might_have\*(C'\fR relationships. You can disable this
behaviour on a per-relationship basis by supplying
\&\f(CW\*(C`cascade_delete => 0\*(C'\fR in the relationship attributes.
.Sp
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.
.IP "cascade_update" 4
.IX Item "cascade_update"
By default, DBIx::Class cascades updates across \f(CW\*(C`has_one\*(C'\fR and
\&\f(CW\*(C`might_have\*(C'\fR relationships. You can disable this behaviour on a
per-relationship basis by supplying \f(CW\*(C`cascade_update => 0\*(C'\fR in
the relationship attributes.
.Sp
The \f(CW\*(C`belongs_to\*(C'\fR relationship does not update across relationships
by default, so if you have a 'proxy' attribute on a belongs_to and want to
use 'update' on it, you must set \f(CW\*(C`cascade_update => 1\*(C'\fR.
.Sp
This is not a \s-1RDMS\s0 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.
.IP "on_delete / on_update" 4
.IX Item "on_delete / on_update"
If you are using SQL::Translator to create \s-1SQL\s0 for you, you can use these
attributes to explicitly set the desired \f(CW\*(C`ON DELETE\*(C'\fR or \f(CW\*(C`ON UPDATE\*(C'\fR constraint
type. If not supplied the \s-1SQLT\s0 parser will attempt to infer the constraint type by
interrogating the attributes of the \fBopposite\fR relationship. For any 'multi'
relationship with \f(CW\*(C`cascade_delete => 1\*(C'\fR, the corresponding belongs_to
relationship will be created with an \f(CW\*(C`ON DELETE CASCADE\*(C'\fR constraint. For any
relationship bearing \f(CW\*(C`cascade_copy => 1\*(C'\fR the resulting belongs_to constraint
will be \f(CW\*(C`ON UPDATE CASCADE\*(C'\fR. If you wish to disable this autodetection, and just
use the \s-1RDBMS\s0' default constraint type, pass \f(CW\*(C`on_delete => undef\*(C'\fR or
\&\f(CW\*(C`on_delete => \*(Aq\*(Aq\*(C'\fR, and the same for \f(CW\*(C`on_update\*(C'\fR respectively.
.IP "is_deferrable" 4
.IX Item "is_deferrable"
Tells SQL::Translator that the foreign key constraint it creates should be
deferrable. In other words, the user may request that the constraint be ignored
until the end of the transaction. Currently, only the PostgreSQL producer
actually supports this.
.IP "add_fk_index" 4
.IX Item "add_fk_index"
Tells SQL::Translator to add an index for this constraint. Can also be
specified globally in the args to \*(L"deploy\*(R" in DBIx::Class::Schema or
\&\*(L"create_ddl_dir\*(R" in DBIx::Class::Schema. Default is on, set to 0 to disable.
.SS "register_relationship"
.IX Subsection "register_relationship"
.ie n .IP "Arguments: $rel_name, $rel_info" 4
.el .IP "Arguments: \f(CW$rel_name\fR, \f(CW$rel_info\fR" 4
.IX Item "Arguments: $rel_name, $rel_info"
.PP
Registers a relationship on the class. This is called internally by
DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
.SS "related_resultset"
.IX Subsection "related_resultset"
.ie n .IP "Arguments: $rel_name" 4
.el .IP "Arguments: \f(CW$rel_name\fR" 4
.IX Item "Arguments: $rel_name"
.PD 0
.ie n .IP "Return Value: $related_resultset" 4
.el .IP "Return Value: \f(CW$related_resultset\fR" 4
.IX Item "Return Value: $related_resultset"
.PD
.PP
.Vb 1
\&  $rs = $cd\->related_resultset(\*(Aqartist\*(Aq);
.Ve
.PP
Returns a DBIx::Class::ResultSet for the relationship named
\&\f(CW$rel_name\fR.
.ie n .SS "$relationship_accessor"
.el .SS "\f(CW$relationship_accessor\fP"
.IX Subsection "$relationship_accessor"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.ie n .IP "Return Value: $result | $related_resultset | undef" 4
.el .IP "Return Value: \f(CW$result\fR | \f(CW$related_resultset\fR | undef" 4
.IX Item "Return Value: $result | $related_resultset | undef"
.PD
.PP
.Vb 5
\&  # These pairs do the same thing
\&  $result = $cd\->related_resultset(\*(Aqartist\*(Aq)\->single;  # has_one relationship
\&  $result = $cd\->artist;
\&  $rs = $cd\->related_resultset(\*(Aqtracks\*(Aq);           # has_many relationship
\&  $rs = $cd\->tracks;
.Ve
.PP
This is the recommended way to traverse through relationships, based
on the \*(L"accessor\*(R" name given in the relationship definition.
.PP
This will return either a Result or a
ResultSet, depending on if the relationship is
\&\f(CW\*(C`single\*(C'\fR (returns only one row) or \f(CW\*(C`multi\*(C'\fR (returns many rows).  The
method may also return \f(CW\*(C`undef\*(C'\fR if the relationship doesn't exist for
this instance (like in the case of \f(CW\*(C`might_have\*(C'\fR relationships).
.SS "search_related"
.IX Subsection "search_related"
.ie n .IP "Arguments: $rel_name, $cond?, \e%attrs?" 4
.el .IP "Arguments: \f(CW$rel_name\fR, \f(CW$cond\fR?, \e%attrs?" 4
.IX Item "Arguments: $rel_name, $cond?, %attrs?"
.PD 0
.ie n .IP "Return Value: $resultset (scalar context) | @result_objs (list context)" 4
.el .IP "Return Value: \f(CW$resultset\fR (scalar context) | \f(CW@result_objs\fR (list context)" 4
.IX Item "Return Value: $resultset (scalar context) | @result_objs (list context)"
.PD
.PP
Run a search on a related resultset. The search will be restricted to the
results represented by the DBIx::Class::ResultSet it was called
upon.
.PP
See \*(L"search_related\*(R" in DBIx::Class::ResultSet for more information.
.SS "search_related_rs"
.IX Subsection "search_related_rs"
This method works exactly the same as search_related, except that
it guarantees a resultset, even in list context.
.SS "count_related"
.IX Subsection "count_related"
.ie n .IP "Arguments: $rel_name, $cond?, \e%attrs?" 4
.el .IP "Arguments: \f(CW$rel_name\fR, \f(CW$cond\fR?, \e%attrs?" 4
.IX Item "Arguments: $rel_name, $cond?, %attrs?"
.PD 0
.ie n .IP "Return Value: $count" 4
.el .IP "Return Value: \f(CW$count\fR" 4
.IX Item "Return Value: $count"
.PD
.PP
Returns the count of all the rows in the related resultset, restricted by the
current result or where conditions.
.SS "new_related"
.IX Subsection "new_related"
.ie n .IP "Arguments: $rel_name, \e%col_data" 4
.el .IP "Arguments: \f(CW$rel_name\fR, \e%col_data" 4
.IX Item "Arguments: $rel_name, %col_data"
.PD 0
.ie n .IP "Return Value: $result" 4
.el .IP "Return Value: \f(CW$result\fR" 4
.IX Item "Return Value: $result"
.PD
.PP
Create a new result object of the related foreign class.  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 result will not be saved into
your storage until you call \*(L"insert\*(R" in DBIx::Class::Row on it.
.SS "create_related"
.IX Subsection "create_related"
.ie n .IP "Arguments: $rel_name, \e%col_data" 4
.el .IP "Arguments: \f(CW$rel_name\fR, \e%col_data" 4
.IX Item "Arguments: $rel_name, %col_data"
.PD 0
.ie n .IP "Return Value: $result" 4
.el .IP "Return Value: \f(CW$result\fR" 4
.IX Item "Return Value: $result"
.PD
.PP
.Vb 1
\&  my $result = $obj\->create_related($rel_name, \e%col_data);
.Ve
.PP
Creates a new result object, similarly to new_related, and also inserts the
result's data into your storage medium. See the distinction between \f(CW\*(C`create\*(C'\fR
and \f(CW\*(C`new\*(C'\fR in DBIx::Class::ResultSet for details.
.SS "find_related"
.IX Subsection "find_related"
.ie n .IP "Arguments: $rel_name, \e%col_data | @pk_values, { key => $unique_constraint, %attrs }?" 4
.el .IP "Arguments: \f(CW$rel_name\fR, \e%col_data | \f(CW@pk_values\fR, { key => \f(CW$unique_constraint\fR, \f(CW%attrs\fR }?" 4
.IX Item "Arguments: $rel_name, %col_data | @pk_values, { key => $unique_constraint, %attrs }?"
.PD 0
.ie n .IP "Return Value: $result | undef" 4
.el .IP "Return Value: \f(CW$result\fR | undef" 4
.IX Item "Return Value: $result | undef"
.PD
.PP
.Vb 1
\&  my $result = $obj\->find_related($rel_name, \e%col_data);
.Ve
.PP
Attempt to find a related object using its primary key or unique constraints.
See \*(L"find\*(R" in DBIx::Class::ResultSet for details.
.SS "find_or_new_related"
.IX Subsection "find_or_new_related"
.ie n .IP "Arguments: $rel_name, \e%col_data, { key => $unique_constraint, %attrs }?" 4
.el .IP "Arguments: \f(CW$rel_name\fR, \e%col_data, { key => \f(CW$unique_constraint\fR, \f(CW%attrs\fR }?" 4
.IX Item "Arguments: $rel_name, %col_data, { key => $unique_constraint, %attrs }?"
.PD 0
.ie n .IP "Return Value: $result" 4
.el .IP "Return Value: \f(CW$result\fR" 4
.IX Item "Return Value: $result"
.PD
.PP
Find a result object of a related class.  See \*(L"find_or_new\*(R" in DBIx::Class::ResultSet
for details.
.SS "find_or_create_related"
.IX Subsection "find_or_create_related"
.ie n .IP "Arguments: $rel_name, \e%col_data, { key => $unique_constraint, %attrs }?" 4
.el .IP "Arguments: \f(CW$rel_name\fR, \e%col_data, { key => \f(CW$unique_constraint\fR, \f(CW%attrs\fR }?" 4
.IX Item "Arguments: $rel_name, %col_data, { key => $unique_constraint, %attrs }?"
.PD 0
.ie n .IP "Return Value: $result" 4
.el .IP "Return Value: \f(CW$result\fR" 4
.IX Item "Return Value: $result"
.PD
.PP
Find or create a result object of a related class. See
\&\*(L"find_or_create\*(R" in DBIx::Class::ResultSet for details.
.SS "update_or_create_related"
.IX Subsection "update_or_create_related"
.ie n .IP "Arguments: $rel_name, \e%col_data, { key => $unique_constraint, %attrs }?" 4
.el .IP "Arguments: \f(CW$rel_name\fR, \e%col_data, { key => \f(CW$unique_constraint\fR, \f(CW%attrs\fR }?" 4
.IX Item "Arguments: $rel_name, %col_data, { key => $unique_constraint, %attrs }?"
.PD 0
.ie n .IP "Return Value: $result" 4
.el .IP "Return Value: \f(CW$result\fR" 4
.IX Item "Return Value: $result"
.PD
.PP
Update or create a result object of a related class. See
\&\*(L"update_or_create\*(R" in DBIx::Class::ResultSet for details.
.SS "set_from_related"
.IX Subsection "set_from_related"
.ie n .IP "Arguments: $rel_name, $result" 4
.el .IP "Arguments: \f(CW$rel_name\fR, \f(CW$result\fR" 4
.IX Item "Arguments: $rel_name, $result"
.PD 0
.IP "Return Value: not defined" 4
.IX Item "Return Value: not defined"
.PD
.PP
.Vb 2
\&  $book\->set_from_related(\*(Aqauthor\*(Aq, $author_obj);
\&  $book\->author($author_obj);                      ## same thing
.Ve
.PP
Set column values on the current object, using related values from the given
related object. This is used to associate previously separate objects, for
example, to set the correct author for a book, find the Author object, then
call set_from_related on the book.
.PP
This is called internally when you pass existing objects as values to
\&\*(L"create\*(R" in DBIx::Class::ResultSet, or pass an object to a belongs_to accessor.
.PP
The columns are only set in the local copy of the object, call
update to update them in the storage.
.SS "update_from_related"
.IX Subsection "update_from_related"
.ie n .IP "Arguments: $rel_name, $result" 4
.el .IP "Arguments: \f(CW$rel_name\fR, \f(CW$result\fR" 4
.IX Item "Arguments: $rel_name, $result"
.PD 0
.IP "Return Value: not defined" 4
.IX Item "Return Value: not defined"
.PD
.PP
.Vb 1
\&  $book\->update_from_related(\*(Aqauthor\*(Aq, $author_obj);
.Ve
.PP
The same as \*(L"set_from_related\*(R", but the changes are immediately updated
in storage.
.SS "delete_related"
.IX Subsection "delete_related"
.ie n .IP "Arguments: $rel_name, $cond?, \e%attrs?" 4
.el .IP "Arguments: \f(CW$rel_name\fR, \f(CW$cond\fR?, \e%attrs?" 4
.IX Item "Arguments: $rel_name, $cond?, %attrs?"
.PD 0
.ie n .IP "Return Value: $underlying_storage_rv" 4
.el .IP "Return Value: \f(CW$underlying_storage_rv\fR" 4
.IX Item "Return Value: $underlying_storage_rv"
.PD
.PP
Delete any related row, subject to the given conditions.  Internally, this
calls:
.PP
.Vb 1
\&  $self\->search_related(@_)\->delete
.Ve
.PP
And returns the result of that.
.SS "add_to_$rel"
.IX Subsection "add_to_$rel"
\&\fBCurrently only available for \f(CB\*(C`has_many\*(C'\fB, \f(CB\*(C`many_to_many\*(C'\fB and 'multi' type
relationships.\fR
.PP
\fIhas_many / multi\fR
.IX Subsection "has_many / multi"
.IP "Arguments: \e%col_data" 4
.IX Item "Arguments: %col_data"
.PD 0
.ie n .IP "Return Value: $result" 4
.el .IP "Return Value: \f(CW$result\fR" 4
.IX Item "Return Value: $result"
.PD
.PP
Creates/inserts a new result object.  Internally, this calls:
.PP
.Vb 1
\&  $self\->create_related($rel, @_)
.Ve
.PP
And returns the result of that.
.PP
\fImany_to_many\fR
.IX Subsection "many_to_many"
.ie n .IP "Arguments: (\e%col_data | $result), \e%link_col_data?" 4
.el .IP "Arguments: (\e%col_data | \f(CW$result\fR), \e%link_col_data?" 4
.IX Item "Arguments: (%col_data | $result), %link_col_data?"
.PD 0
.ie n .IP "Return Value: $result" 4
.el .IP "Return Value: \f(CW$result\fR" 4
.IX Item "Return Value: $result"
.PD
.PP
.Vb 3
\&  my $role = $schema\->resultset(\*(AqRole\*(Aq)\->find(1);
\&  $actor\->add_to_roles($role);
\&      # creates a My::DBIC::Schema::ActorRoles linking table result object
\&
\&  $actor\->add_to_roles({ name => \*(Aqlead\*(Aq }, { salary => 15_000_000 });
\&      # creates a new My::DBIC::Schema::Role result object and the linking table
\&      # object with an extra column in the link
.Ve
.PP
Adds a linking table object. If the first argument is a hash reference, the
related object is created first with the column values in the hash. If an object
reference is given, just the linking table object is created. In either case,
any additional column values for the linking table object can be specified in
\&\f(CW\*(C`\e%link_col_data\*(C'\fR.
.PP
See \*(L"many_to_many\*(R" in DBIx::Class::Relationship for additional details.
.SS "set_$rel"
.IX Subsection "set_$rel"
\&\fBCurrently only available for \f(CB\*(C`many_to_many\*(C'\fB relationships.\fR
.ie n .IP "Arguments: (\e@hashrefs_of_col_data | \e@result_objs), $link_vals?" 4
.el .IP "Arguments: (\e@hashrefs_of_col_data | \e@result_objs), \f(CW$link_vals\fR?" 4
.IX Item "Arguments: (@hashrefs_of_col_data | @result_objs), $link_vals?"
.PD 0
.IP "Return Value: not defined" 4
.IX Item "Return Value: not defined"
.PD
.PP
.Vb 3
\&  my $actor = $schema\->resultset(\*(AqActor\*(Aq)\->find(1);
\&  my @roles = $schema\->resultset(\*(AqRole\*(Aq)\->search({ role =>
\&     { \*(Aq\-in\*(Aq => [\*(AqFred\*(Aq, \*(AqBarney\*(Aq] } } );
\&
\&  $actor\->set_roles(\e@roles);
\&     # Replaces all of $actor\*(Aqs previous roles with the two named
\&
\&  $actor\->set_roles(\e@roles, { salary => 15_000_000 });
\&     # Sets a column in the link table for all roles
.Ve
.PP
Replace all the related objects with the given reference to a list of
objects. This does a \f(CW\*(C`delete\*(C'\fR \fBon the link table resultset\fR to remove the
association between the current object and all related objects, then calls
\&\f(CW\*(C`add_to_$rel\*(C'\fR repeatedly to link all the new objects.
.PP
Note that this means that this method will \fBnot\fR delete any objects in the
table on the right side of the relation, merely that it will delete the link
between them.
.PP
Due to a mistake in the original implementation of this method, it will also
accept a list of objects or hash references. This is \fBdeprecated\fR and will be
removed in a future version.
.SS "remove_from_$rel"
.IX Subsection "remove_from_$rel"
\&\fBCurrently only available for \f(CB\*(C`many_to_many\*(C'\fB relationships.\fR
.ie n .IP "Arguments: $result" 4
.el .IP "Arguments: \f(CW$result\fR" 4
.IX Item "Arguments: $result"
.PD 0
.IP "Return Value: not defined" 4
.IX Item "Return Value: not defined"
.PD
.PP
.Vb 3
\&  my $role = $schema\->resultset(\*(AqRole\*(Aq)\->find(1);
\&  $actor\->remove_from_roles($role);
\&      # removes $role\*(Aqs My::DBIC::Schema::ActorRoles linking table result object
.Ve
.PP
Removes the link between the current object and the related object. Note that
the related object itself won't be deleted unless you call \->\fBdelete()\fR on
it. This method just removes the link between the two objects.
.SH "FURTHER QUESTIONS?"
.IX Header "FURTHER QUESTIONS?"
Check the list of additional \s-1DBIC\s0 resources.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This module is free software copyright
by the DBIx::Class (\s-1DBIC\s0) authors. You can
redistribute it and/or modify it under the same terms as the
DBIx::Class library.