Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DBIx::Class::RelationsUser3Contributed Perl DocumeDBIx::Class::Relationship(3)

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

SYNOPSIS
	 ## Creating relationships
	 MyApp::Schema::Actor->has_many('actorroles' =>	'MyApp::Schema::ActorRole',
				       'actor');
	 MyApp::Schema::Role->has_many('actorroles' => 'MyApp::Schema::ActorRole',
				       'role');
	 MyApp::Schema::ActorRole->belongs_to('role' =>	'MyApp::Schema::Role');
	 MyApp::Schema::ActorRole->belongs_to('actor' => 'MyApp::Schema::Actor');

	 MyApp::Schema::Role->many_to_many('actors' => 'actorroles', 'actor');
	 MyApp::Schema::Actor->many_to_many('roles' => 'actorroles', 'role');

	 ## Using relationships
	 $schema->resultset('Actor')->find({ id	=> 1})->roles();
	 $schema->resultset('Role')->find({ id => 1 })->actorroles->search_related('actor', { Name => 'Fred' });
	 $schema->resultset('Actor')->add_to_roles({ Name => 'Sherlock Holmes'});

       See DBIx::Class::Manual::Cookbook for more.

DESCRIPTION
       The word	Relationship has a specific meaning in DBIx::Class, see	the
       definition in the Glossary.

       This class provides methods to set up relationships between the tables
       in your database	model. Relationships are the most useful and powerful
       technique that DBIx::Class provides. To create efficient	database
       queries,	create relationships between any and all tables	that have
       something in common, for	example	if you have a table Authors:

	 ID  | Name | Age
	------------------
	  1  | Fred | 30
	  2  | Joe  | 32

       and a table Books:

	 ID  | Author |	Name
	--------------------
	  1  |	    1 |	Rulers of the universe
	  2  |	    1 |	Rulers of the galaxy

       Then without relationships, the method of getting all books by Fred
       goes like this:

	my $fred = $schema->resultset('Author')->find({	Name =>	'Fred' });
	my $fredsbooks = $schema->resultset('Book')->search({ Author =>	$fred->ID });

       With a has_many relationship called "books" on Author (see below	for
       details), we can	do this	instead:

	my $fredsbooks = $schema->resultset('Author')->find({ Name => 'Fred' })->books;

       Each relationship sets up an accessor method on the Result objects that
       represent the items of your table. From ResultSet objects, the
       relationships can be searched using the "search_related"	method.	 In
       list context, each returns a list of Result objects for the related
       class, in scalar	context, a new ResultSet representing the joined
       tables is returned. Thus, the calls can be chained to produce complex
       queries.	 Since the database is not actually queried until you attempt
       to retrieve the data for	an actual item,	no time	is wasted producing
       them.

	my $cheapfredbooks = $schema->resultset('Author')->find({
	  Name => 'Fred',
	})->books->search_related('prices', {
	  Price	=> { '<=' => '5.00' },
	});

       will produce a query something like:

	SELECT * FROM Author me
	LEFT JOIN Books	books ON books.author =	me.id
	LEFT JOIN Prices prices	ON prices.book = books.id
	WHERE prices.Price <= 5.00

       all without needing multiple fetches.

       Only the	helper methods for setting up standard relationship types are
       documented here.	For the	basic, lower-level methods, and	a description
       of all the useful *_related methods that	you get	for free, see
       DBIx::Class::Relationship::Base.

METHODS
       All helper methods are called similar to	the following template:

	 __PACKAGE__->$method_name('rel_name', 'Foreign::Class', \%cond|\@cond|\&cond?,	\%attrs?);

       Both "cond" and "attrs" are optional. Pass "undef" for "cond" if	you
       want to use the default value for it, but still want to set "attrs".

       See "condition" in DBIx::Class::Relationship::Base for full
       documentation on	definition of the "cond" argument.

       See "attributes"	in DBIx::Class::Relationship::Base for documentation
       on the attributes that are allowed in the "attrs" argument.

   belongs_to
       Arguments: $accessor_name, $related_class,
       $our_fk_column|\%cond|\@cond|\$cond?, \%attrs?

       Creates a relationship where the	calling	class stores the foreign
       class's primary key in one (or more) of the calling class columns.
       This relationship defaults to using $accessor_name as the column	name
       in this class to	resolve	the join against the primary key from
       $related_class, unless $our_fk_column specifies the foreign key column
       in this class or	"cond" specifies a reference to	a join condition.

       accessor_name
	   This	argument is the	name of	the method you can call	on a Result
	   object to retrieve the instance of the foreign class	matching this
	   relationship. This is often called the "relation(ship) name".

	   Use this accessor_name in "join" in DBIx::Class::ResultSet or
	   "prefetch" in DBIx::Class::ResultSet	to join	to the foreign table
	   indicated by	this relationship.

       related_class
	   This	is the class name of the table referenced by the foreign key
	   in this class.

       our_fk_column
	   The column name on this class that contains the foreign key.

	   OR

       cond
	   A hashref, arrayref or coderef specifying a custom join expression.
	   For more info see "condition" in DBIx::Class::Relationship::Base.

	 # in a	Book class (where Author has many Books)
	 My::DBIC::Schema::Book->belongs_to(
	   author =>
	   'My::DBIC::Schema::Author',
	   'author_id'
	 );

	 # OR (same result)
	 My::DBIC::Schema::Book->belongs_to(
	   author =>
	   'My::DBIC::Schema::Author',
	   { 'foreign.author_id' => 'self.author_id' }
	 );

	 # OR (similar result but uglier accessor name)
	 My::DBIC::Schema::Book->belongs_to(
	   author_id =>
	   'My::DBIC::Schema::Author'
	 );

	 # Usage
	 my $author_obj	= $book->author; # get author object
	 $book->author(	$new_author_obj	); # set author	object
	 $book->author_id(); # get the plain id

	 # To retrieve the plain id if you used	the ugly version:
	 $book->get_column('author_id');

       If some of the foreign key columns are nullable you probably want to
       set the join_type attribute to "left" explicitly	so that	SQL expressing
       this relation is	composed with a	"LEFT JOIN" (as	opposed	to "INNER
       JOIN" which is default for "belongs_to" relationships). This ensures
       that relationship traversal works consistently in all situations. (i.e.
       resultsets involving join or prefetch).	The modified declaration is
       shown below:

	 # in a	Book class (where Author has_many Books)
	 __PACKAGE__->belongs_to(
	   author =>
	   'My::DBIC::Schema::Author',
	   'author',
	   { join_type => 'left' }
	 );

       Cascading deletes are off by default on a "belongs_to" relationship. To
       turn them on, pass "cascade_delete => 1"	in the $attr hashref.

       By default, DBIC	will return undef and avoid querying the database if a
       "belongs_to" accessor is	called when any	part of	the foreign key	IS
       NULL. To	disable	this behavior, pass "undef_on_null_fk => 0" in the
       "\%attrs" hashref.

       NOTE: If	you are	used to	Class::DBI relationships, this is the
       equivalent of "has_a".

       See "attributes"	in DBIx::Class::Relationship::Base for documentation
       on relationship methods and valid relationship attributes. Also see
       DBIx::Class::ResultSet for a list of standard resultset attributes
       which can be assigned to	relationships as well.

   has_many
       Arguments: $accessor_name, $related_class,
       $their_fk_column|\%cond|\@cond|\&cond?, \%attrs?

       Creates a one-to-many relationship where	the foreign class refers to
       this class's primary key. This relationship refers to zero or more
       records in the foreign table (e.g. a "LEFT JOIN"). This relationship
       defaults	to using the end of this classes namespace as the foreign key
       in $related_class to resolve the	join, unless $their_fk_column
       specifies the foreign key column	in $related_class or "cond" specifies
       a reference to a	join condition.

       accessor_name
	   This	argument is the	name of	the method you can call	on a Result
	   object to retrieve a	resultset of the related class restricted to
	   the ones related to the result object. In list context it returns
	   the result objects. This is often called the	"relation(ship)	name".

	   Use this accessor_name in "join" in DBIx::Class::ResultSet or
	   "prefetch" in DBIx::Class::ResultSet	to join	to the foreign table
	   indicated by	this relationship.

       related_class
	   This	is the class name of the table which contains a	foreign	key
	   column containing PK	values of this class.

       their_fk_column
	   The column name on the related class	that contains the foreign key.

	   OR

       cond
	   A hashref, arrayref	or coderef specifying a	custom join
	   expression. For more	info see "condition" in
	   DBIx::Class::Relationship::Base.

	 # in an Author	class (where Author has_many Books)
	 # assuming related class is storing our PK in "author_id"
	 My::DBIC::Schema::Author->has_many(
	   books =>
	   'My::DBIC::Schema::Book',
	   'author_id'
	 );

	 # OR (same result)
	 My::DBIC::Schema::Author->has_many(
	   books =>
	   'My::DBIC::Schema::Book',
	   { 'foreign.author_id' => 'self.id' },
	 );

	 # OR (similar result, assuming	related_class is storing our PK, in "author")
	 # (the	"author" is guessed at from "Author" in	the class namespace)
	 My::DBIC::Schema::Author->has_many(
	   books =>
	   'My::DBIC::Schema::Book',
	 );

	 # Usage
	 # resultset of	Books belonging	to author
	 my $booklist =	$author->books;

	 # resultset of	Books belonging	to author, restricted by author	name
	 my $booklist =	$author->books({
	   name	=> { LIKE => '%macaroni%' },
	   { prefetch => [qw/book/],
	 });

	 # array of Book objects belonging to author
	 my @book_objs = $author->books;

	 # force resultset even	in list	context
	 my $books_rs =	$author->books;
	 ( $books_rs ) = $obj->books_rs;

	 # create a new	book for this author, the relation fields are auto-filled
	 $author->create_related('books', \%col_data);
	 # alternative method for the above
	 $author->add_to_books(\%col_data);

       Three methods are created when you create a has_many relationship.  The
       first method is the expected accessor method, "$accessor_name()".  The
       second is almost	exactly	the same as the	accessor method	but "_rs" is
       added to	the end	of the method name, eg "$accessor_name_rs()".  This
       method works just like the normal accessor, except that it always
       returns a resultset, even in list context. The third method, named
       "add_to_$rel_name", will	also be	added to your Row items; this allows
       you to insert new related items,	using the same mechanism as in
       "create_related"	in DBIx::Class::Relationship::Base.

       If you delete an	object in a class with a "has_many" relationship, all
       the related objects will	be deleted as well.  To	turn this behaviour
       off, pass "cascade_delete => 0" in the $attr hashref.

       The cascaded operations are performed after the requested delete	or
       update, 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.

       If you copy an object in	a class	with a "has_many" relationship,	all
       the related objects will	be copied as well. To turn this	behaviour off,
       pass "cascade_copy => 0"	in the $attr hashref. The behaviour defaults
       to "cascade_copy	=> 1".

       See "attributes"	in DBIx::Class::Relationship::Base for documentation
       on relationship methods and valid relationship attributes. Also see
       DBIx::Class::ResultSet for a list of standard resultset attributes
       which can be assigned to	relationships as well.

   might_have
       Arguments: $accessor_name, $related_class,
       $their_fk_column|\%cond|\@cond|\&cond?, \%attrs?

       Creates an optional one-to-one relationship with	a class. This
       relationship defaults to	using $accessor_name as	the foreign key	in
       $related_class to resolve the join, unless $their_fk_column specifies
       the foreign key column in $related_class	or "cond" specifies a
       reference to a join condition.

       accessor_name
	   This	argument is the	name of	the method you can call	on a Result
	   object to retrieve the instance of the foreign class	matching this
	   relationship. This is often called the "relation(ship) name".

	   Use this accessor_name in "join" in DBIx::Class::ResultSet or
	   "prefetch" in DBIx::Class::ResultSet	to join	to the foreign table
	   indicated by	this relationship.

       related_class
	   This	is the class name of the table which contains a	foreign	key
	   column containing PK	values of this class.

       their_fk_column
	   The column name on the related class	that contains the foreign key.

	   OR

       cond
	   A hashref, arrayref	or coderef specifying a	custom join
	   expression. For more	info see "condition" in
	   DBIx::Class::Relationship::Base.

	 # Author may have an entry in the pseudonym table
	 My::DBIC::Schema::Author->might_have(
	   pseudonym =>
	   'My::DBIC::Schema::Pseudonym',
	   'author_id',
	 );

	 # OR (same result, assuming the related_class stores our PK)
	 My::DBIC::Schema::Author->might_have(
	   pseudonym =>
	   'My::DBIC::Schema::Pseudonym',
	 );

	 # OR (same result)
	 My::DBIC::Schema::Author->might_have(
	   pseudonym =>
	   'My::DBIC::Schema::Pseudonym',
	   { 'foreign.author_id' => 'self.id' },
	 );

	 # Usage
	 my $pname = $author->pseudonym; # to get the Pseudonym	object

       If you update or	delete an object in a class with a "might_have"
       relationship, the related object	will be	updated	or deleted as well. To
       turn off	this behavior, add "cascade_delete => 0" to the	$attr hashref.

       The cascaded operations are performed after the requested delete	or
       update, 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.

       See "attributes"	in DBIx::Class::Relationship::Base for documentation
       on relationship methods and valid relationship attributes. Also see
       DBIx::Class::ResultSet for a list of standard resultset attributes
       which can be assigned to	relationships as well.

       Note that if you	supply a condition on which to join, and the column in
       the current table allows	nulls (i.e., has the "is_nullable" attribute
       set to a	true value), than "might_have" will warn about this because
       it's naughty and	you shouldn't do that. The warning will	look something
       like:

	 "might_have/has_one" must not be on columns with is_nullable set to true (MySchema::SomeClass/key)

       If you must be naughty, you can suppress	the warning by setting
       "DBIC_DONT_VALIDATE_RELS" environment variable to a true	value.
       Otherwise, you probably just meant to use
       "DBIx::Class::Relationship/belongs_to".

   has_one
       Arguments: $accessor_name, $related_class,
       $their_fk_column|\%cond|\@cond|\&cond?, \%attrs?

       Creates a one-to-one relationship with a	class. This relationship
       defaults	to using $accessor_name	as the foreign key in $related_class
       to resolve the join, unless $their_fk_column specifies the foreign key
       column in $related_class	or "cond" specifies a reference	to a join
       condition.

       accessor_name
	   This	argument is the	name of	the method you can call	on a Result
	   object to retrieve the instance of the foreign class	matching this
	   relationship. This is often called the "relation(ship) name".

	   Use this accessor_name in "join" in DBIx::Class::ResultSet or
	   "prefetch" in DBIx::Class::ResultSet	to join	to the foreign table
	   indicated by	this relationship.

       related_class
	   This	is the class name of the table which contains a	foreign	key
	   column containing PK	values of this class.

       their_fk_column
	   The column name on the related class	that contains the foreign key.

	   OR

       cond
	   A hashref, arrayref	or coderef specifying a	custom join
	   expression. For more	info see "condition" in
	   DBIx::Class::Relationship::Base.

	 # Every book has exactly one ISBN
	 My::DBIC::Schema::Book->has_one(
	   isbn	=>
	   'My::DBIC::Schema::ISBN',
	   'book_id',
	 );

	 # OR (same result, assuming related_class stores our PK)
	 My::DBIC::Schema::Book->has_one(
	   isbn	=>
	   'My::DBIC::Schema::ISBN',
	 );

	 # OR (same result)
	 My::DBIC::Schema::Book->has_one(
	   isbn	=>
	   'My::DBIC::Schema::ISBN',
	   { 'foreign.book_id' => 'self.id' },
	 );

	 # Usage
	 my $isbn_obj =	$book->isbn; # to get the ISBN object

       Creates a one-to-one relationship with another class. This is just like
       "might_have", except the	implication is that the	other object is	always
       present.	The only difference between "has_one" and "might_have" is that
       "has_one" uses an (ordinary) inner join,	whereas	"might_have" defaults
       to a left join.

       The has_one relationship	should be used when a row in the table must
       have exactly one	related	row in another table. If the related row might
       not exist in the	foreign	table, use the "might_have" in
       DBIx::Class::Relationship relationship.

       In the above example, each Book in the database is associated with
       exactly one ISBN	object.

       See "attributes"	in DBIx::Class::Relationship::Base for documentation
       on relationship methods and valid relationship attributes. Also see
       DBIx::Class::ResultSet for a list of standard resultset attributes
       which can be assigned to	relationships as well.

       Note that if you	supply a condition on which to join, if	the column in
       the current table allows	nulls (i.e., has the "is_nullable" attribute
       set to a	true value), than warnings might apply just as with
       "might_have" in DBIx::Class::Relationship.

   many_to_many
       Arguments: $accessor_name, $link_rel_name, $foreign_rel_name, \%attrs?

       "many_to_many" is a Relationship	bridge which has a specific meaning in
       DBIx::Class, see	the definition in the Glossary.

       "many_to_many" is not strictly a	relationship in	its own	right.
       Instead,	it is a	bridge between two resultsets which provide the	same
       kind of convenience accessors as	true relationships provide. Although
       the accessor will return	a resultset or collection of objects just like
       has_many	does, you cannot call "related_resultset" and similar methods
       which operate on	true relationships.

       accessor_name
	   This	argument is the	name of	the method you can call	on a Result
	   object to retrieve the rows matching	this relationship.

	   On a	many_to_many, unlike other relationships, this cannot be used
	   in "search" in DBIx::Class::ResultSet to join tables. Use the
	   relations bridged across instead.

       link_rel_name
	   This	is the accessor_name from the has_many relationship we are
	   bridging from.

       foreign_rel_name
	   This	is the accessor_name of	the belongs_to relationship in the
	   link	table that we are bridging across (which gives us the table we
	   are bridging	to).

       To create a many_to_many	relationship from Actor	to Role:

	 My::DBIC::Schema::Actor->has_many( actor_roles	=>
					    'My::DBIC::Schema::ActorRoles',
					    'actor' );
	 My::DBIC::Schema::ActorRoles->belongs_to( role	=>
						   'My::DBIC::Schema::Role' );
	 My::DBIC::Schema::ActorRoles->belongs_to( actor =>
						   'My::DBIC::Schema::Actor' );

	 My::DBIC::Schema::Actor->many_to_many(	roles => 'actor_roles',
						'role' );

       And, for	the reverse relationship, from Role to Actor:

	 My::DBIC::Schema::Role->has_many( actor_roles =>
					   'My::DBIC::Schema::ActorRoles',
					   'role' );

	 My::DBIC::Schema::Role->many_to_many( actors => 'actor_roles',	'actor'	);

       To add a	role for your actor, and fill in the year of the role in the
       actor_roles table:

	 $actor->add_to_roles($role, { year => 1995 });

       In the above example, ActorRoles	is the link table class, and Role is
       the foreign class. The $link_rel_name parameter is the name of the
       accessor	for the	has_many relationship from this	table to the link
       table, and the $foreign_rel_name	parameter is the accessor for the
       belongs_to relationship from the	link table to the foreign table.

       To use many_to_many, existing relationships from	the original table to
       the link	table, and from	the link table to the end table	must already
       exist, these relation names are then used in the	many_to_many call.

       In the above example, the Actor class will have 3 many_to_many accessor
       methods set: "roles", "add_to_roles", "set_roles", and similarly	named
       accessors will be created for the Role class for	the "actors"
       many_to_many relationship.

       See "attributes"	in DBIx::Class::Relationship::Base for documentation
       on relationship methods and valid relationship attributes. Also see
       DBIx::Class::ResultSet for a list of standard resultset attributes
       which can be assigned to	relationships as well.

FURTHER	QUESTIONS?
       Check the list of additional DBIC resources.

COPYRIGHT AND LICENSE
       This module is free software copyright by the DBIx::Class (DBIC)
       authors.	You can	redistribute it	and/or modify it under the same	terms
       as the DBIx::Class library.

perl v5.24.1			  2016-06-17	  DBIx::Class::Relationship(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | FURTHER QUESTIONS? | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DBIx::Class::Relationship&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help