/ 
DBIx-Class-0.06003
River stage three • 349 direct dependents • 459 total dependents
/ DBIx::Class::Relationship::Base

NAME

DBIx::Class::Relationship::Base - Inter-table relationships

SYNOPSIS

DESCRIPTION

This class provides methods to describe the relationships between the tables in your database model. These are the "bare bones" relationships methods, for predefined ones, look in DBIx::Class::Relationship.

METHODS

add_relationship

Arguments: 'relname', 'Foreign::Class', $cond, $attrs
__PACKAGE__->add_relationship('relname', 'Foreign::Class', $cond, $attrs);

The condition needs to be an SQL::Abstract-style representation of the join between the tables. When resolving the condition for use in a JOIN, keys using the pseudo-table foreign are resolved to mean "the Table on the other side of the relationship", and values using the pseudo-table 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 JOIN parameter support.

For example, if you're creating a relationship from Author to Book, where the Book table has a column author_id containing the ID of the Author row:

{ 'foreign.author_id' => 'self.id' }

will result in the JOIN clause

author me JOIN book book ON book.author_id = me.id

For multi-column foreign keys, you will need to specify a foreign-to-self mapping for each column in the key. For example, if you're creating a relationship from Book to Edition, where the Edition table refers to a publisher and a type (e.g. "paperback"):

{
  'foreign.publisher_id' => 'self.publisher_id',
  'foreign.type_id'      => 'self.type_id',
}

This will result in the 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 ANDed conditions. To add an ORed condition, use an arrayref of hashrefs. See the SQL::Abstract documentation for more details.

Valid attributes are as follows:

join_type

Explicitly specifies the type of join to use in the relationship. Any SQL join type is valid, e.g. LEFT or RIGHT. It will be placed in the SQL command immediately before JOIN.

proxy

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
accessor

Specifies the type of accessor that should be created for the relationship. Valid values are single (for when there is only a single related object), multi (when there can be many), and filter (for when there is a single related object, but you also want the relationship accessor to double as a column accessor). For multi accessors, an add_to_* method is also created, which calls create_related for the relationship.

register_relationship

Arguments: $relname, $rel_info

Registers a relationship on the class. This is called internally by DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.

Arguments: $relationship_name
Return Value: $related_resultset
$rs = $cd->related_resultset('artist');

Returns a DBIx::Class::ResultSet for the relationship named $relationship_name.

$rs->search_related('relname', $cond, $attrs);

Run a search on a related resultset. The search will be restricted to the item or items represented by the DBIx::Class::ResultSet it was called upon. This method can be called on a ResultSet, a Row or a ResultSource class.

$obj->count_related('relname', $cond, $attrs);

Returns the count of all the items in the related resultset, restricted by the current item or where conditions. Can be called on a "ResultSet" in DBIx::Class::Manual::Glossary or a "Row" in DBIx::Class::Manual::Glossary object.

my $new_obj = $obj->new_related('relname', \%col_data);

Create a new item of the related foreign class. If called on a "Row" in DBIx::Class::Manual::Glossary object, it will magically set any primary key values into foreign key columns for you. The newly created item will not be saved into your storage until you call "insert" in DBIx::Class::Row on it.

my $new_obj = $obj->create_related('relname', \%col_data);

Creates a new item, similarly to new_related, and also inserts the item's data into your storage medium. See the distinction between create and new in DBIx::Class::ResultSet for details.

my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals);

Attempt to find a related object using its primary key or unique constraints. See "find" in DBIx::Class::ResultSet for details.

my $new_obj = $obj->find_or_create_related('relname', \%col_data);

Find or create an item of a related class. See "find_or_create" in DBIx::Class::ResultSet for details.

$book->set_from_related('author', $author_obj);

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.

The columns are only set in the local copy of the object, call "update" to set them in the storage.

$book->update_from_related('author', $author_obj);

The same as "set_from_related", but the changes are immediately updated in storage.

$obj->delete_related('relname', $cond, $attrs);

Delete any related item subject to the given conditions.

AUTHORS

Matt S. Trout <mst@shadowcatsystems.co.uk>

LICENSE

You may distribute this code under the same terms as Perl itself.