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 DBIx::Class::Relationship.
__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.
JOIN
foreign
self
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:
Author
Book
author_id
{ '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"):
Edition
{ '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.
AND
OR
The standard 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:
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.
LEFT
RIGHT
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
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 cd_title on the $track row object.
cd_title
$track
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' } ], });
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.
single
multi
filter
create_related
If you are using 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 should, set this attribute to a true or false value to override the detection of when to create constraints.
If cascade_copy is true on a 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 cascade_copy => 0 in the $attr hashref.
cascade_copy
has_many
cascade_copy => 0
$attr
The behaviour defaults to cascade_copy => 1 for has_many relationships.
cascade_copy => 1
By default, DBIx::Class cascades deletes across has_many, has_one and might_have relationships. You can disable this behaviour on a per-relationship basis by supplying cascade_delete => 0 in the relationship attributes.
has_one
might_have
cascade_delete => 0
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.
By default, DBIx::Class cascades updates across has_one and might_have relationships. You can disable this behaviour on a per-relationship basis by supplying cascade_update => 0 in the relationship attributes.
cascade_update => 0
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.
If you are using SQL::Translator to create SQL for you, you can use these attributes to explicitly set the desired ON DELETE or ON UPDATE constraint type. If not supplied the SQLT parser will attempt to infer the constraint type by interrogating the attributes of the opposite relationship. For any 'multi' relationship with cascade_delete => 1, the corresponding belongs_to relationship will be created with an ON DELETE CASCADE constraint. For any relationship bearing cascade_copy => 1 the resulting belongs_to constraint will be ON UPDATE CASCADE. If you wish to disable this autodetection, and just use the RDBMS' default constraint type, pass on_delete => undef or on_delete => '', and the same for on_update respectively.
ON DELETE
ON UPDATE
cascade_delete => 1
ON DELETE CASCADE
ON UPDATE CASCADE
on_delete => undef
on_delete => ''
on_update
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.
Tells SQL::Translator to add an index for this constraint. Can also be specified globally in the args to "deploy" in DBIx::Class::Schema or "create_ddl_dir" in DBIx::Class::Schema. Default is on, set to 0 to disable.
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 DBIx::Class::ResultSet 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 DBIx::Class::ResultSet 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 guarantees a resultset, 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 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 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 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.
create
new
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_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 DBIx::Class::Row 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 DBIx::Class::ResultSet 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 DBIx::Class::ResultSet 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 DBIx::Class::ResultSet, or pass an object to a belongs_to accessor.
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.
many-to-many
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.
$obj
$foreign_vals
$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 $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 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.
delete
add_to_$rel
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.
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.
To install DBIx::Class, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DBIx::Class
CPAN shell
perl -MCPAN -e shell install DBIx::Class
For more information on module installation, please visit the detailed CPAN module installation guide.