| DBIx::Class::Relationship::Base - Inter-table relationships |
DBIx::Class::Relationship::Base - Inter-table relationships
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 the DBIx::Class::Relationship manpage.
__PACKAGE__->add_relationship('relname', 'Foreign::Class', $cond, $attrs);
The condition needs to be an the SQL::Abstract manpage-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
the SQL::Abstract manpage documentation for more details.
In addition to standard result set attributes, the following attributes are also valid:
LEFT or RIGHT. It will be placed in the SQL
command immediately before JOIN.
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 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.
Registers a relationship on the class. This is called internally by DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
$rs = $cd->related_resultset('artist');
Returns a the DBIx::Class::ResultSet manpage for the relationship named $relationship_name.
@objects = $rs->search_related('relname', $cond, $attrs);
$objects_rs = $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 the DBIx::Class::ResultSet manpage it was called upon. This method can be called on a ResultSet, a Row or a ResultSource class.
( $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.
$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 the DBIx::Class::Manual::Glossary manpage or a Row in the DBIx::Class::Manual::Glossary manpage object.
my $new_obj = $obj->new_related('relname', \%col_data);
Create a new item of the related foreign class. If called on a 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 insert in the DBIx::Class::Row manpage 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 the DBIx::Class::ResultSet manpage 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 the DBIx::Class::ResultSet manpage for details.
my $new_obj = $obj->find_or_new_related('relname', \%col_data);
Find an item of a related class. If none exists, instantiate a new item of the related class. The object will not be saved into your storage until you call insert in the DBIx::Class::Row manpage on it.
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 the DBIx::Class::ResultSet manpage for details.
my $updated_item = $obj->update_or_create_related('relname', \%col_data, \%attrs?);
Update or create an item of a related class. See update_or_create in the DBIx::Class::ResultSet manpage for details.
$book->set_from_related('author', $author_obj);
$book->author($author_obj); ## same thing
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.
This is called internally when you pass existing objects as values to create in the DBIx::Class::ResultSet manpage, or pass an object to a belongs_to acessor.
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.
Currently only available for has_many, many-to-many and 'multi' type
relationships.
my $role = $schema->resultset('Role')->find(1);
$actor->add_to_roles($role);
# creates a My::DBIC::Schema::ActorRoles linking table row object
$actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
# creates a new My::DBIC::Schema::Role row object and the linking table
# object with an extra column in the link
Adds a linking table object for $obj or $foreign_vals. 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 $link_vals.
Currently only available for many-to-many relationships.
my $actor = $schema->resultset('Actor')->find(1);
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
Replace all the related objects with the given reference to a list of
objects. This does a delete on the link table resultset to remove the
association between the current object and all related objects, then calls
add_to_$rel repeatedly to link all the new objects.
Note that this means that this method will not delete any objects in the table on the right side of the relation, merely that it will delete the link between them.
Due to a mistake in the original implementation of this method, it will also accept a list of objects or hash references. This is deprecated and will be removed in a future version.
Currently only available for many-to-many relationships.
my $role = $schema->resultset('Role')->find(1);
$actor->remove_from_roles($role);
# removes $role's My::DBIC::Schema::ActorRoles linking table row object
Removes the link between the current object and the related object. Note that
the related object itself won't be deleted unless you call ->delete() on
it. This method just removes the link between the two objects.
Matt S. Trout <mst@shadowcatsystems.co.uk>
You may distribute this code under the same terms as Perl itself.
| DBIx::Class::Relationship::Base - Inter-table relationships |