=head2 belongs_to
+=over 4
+
+=item Arguments: $accessor_name, $related_class, $foreign_key_column?, $attr?
+
+=back
+
# in a Book class (where Author has many Books)
My::DBIC::Schema::Book->belongs_to(author => 'My::DBIC::Schema::Author');
my $author_obj = $obj->author;
Creates a relationship where the calling class stores the foreign class's
primary key in one (or more) of its columns. If C<$cond> is a column name
-instead of a join condition hash, that is used as the name of the column
-holding the foreign key. If C<$cond> is not given, the relname is used as
-the column name.
-
-If the relationship is optional - i.e. the column containing the foreign
-key can be NULL - then the belongs_to relationship does the right
-thing - so in the example above C<$obj-E<gt>author> would return C<undef>.
-However in this case you would probably want to set the C<join_type>
-attribute so that a C<LEFT JOIN> is done, which makes complex
-resultsets involving C<join> or C<prefetch> operations work correctly.
-The modified declaration is shown below:
+instead of a join condition hash, it is used as the name of the foreign key
+column in the calling class. If C<$cond> is not given, C<$accessor_name> is
+used as the column name.
+
+If the relationship is optional -- i.e. the column containing the foreign key
+can be NULL -- then the belongs_to relationship does the right thing. Thus, in
+the example above C<$obj-E<gt>author> would return C<undef>. However in this
+case you would probably want to set the C<join_type> attribute so that a C<LEFT
+JOIN> is done, which makes complex resultsets involving C<join> or C<prefetch>
+operations work correctly. The modified declaration is shown below:
# in a Book class (where Author has_many Books)
__PACKAGE__->belongs_to(author => 'My::DBIC::Schema::Author',
=head2 has_many
+=over 4
+
+=item Arguments: $accessor_name, $related_class, $foreign_key_column?, $attr?
+
+=back
+
# in an Author class (where Author has_many Books)
My::DBIC::Schema::Author->has_many(books => 'My::DBIC::Schema::Book', 'author');
my $booklist = $obj->books;
C<$cond> argument, or specify a complete join condition.
Three methods are created when you create a has_many relationship. The first
-method is the expected accessor method. The second is almost exactly the same
-as the accessor method but "_rs" is added to the end of the method name. This
-method works just like the normal accessor, except that it returns a resultset
-no matter what, even in list context. The third method, named
-C<< add_to_<relname> >>, will also be added to your Row items; this allows
-you to insert new related items, using the same mechanism as in
+method is the expected accessor method, C<$accessor_name()>. The second is
+almost exactly the same as the accessor method but "_rs" is added to the end of
+the method name. This method works just like the normal accessor, except that
+it returns a resultset no matter what, even in list context. The third method,
+named C<< add_to_<relname> >>, will also be added to your Row items; this
+allows you to insert new related items, using the same mechanism as in
L<DBIx::Class::Relationship::Base/"create_related">.
If you delete an object in a class with a C<has_many> relationship, all
=head2 might_have
+=over 4
+
+=item Arguments: $accessor_name, $related_class, $join_condition?, $attr?
+
+=back
+
My::DBIC::Schema::Author->might_have(pseudonym =>
- 'My::DBIC::Schema::Pseudonyms');
+ 'My::DBIC::Schema::Pseudonym');
+
my $pname = $obj->pseudonym; # to get the Pseudonym object
-Creates an optional one-to-one relationship with a class, where the foreign
-class stores our primary key in one of its columns. Defaults to the primary
-key of the foreign class unless C<$cond> specifies a column or join condition.
+Creates an optional one-to-one relationship with a class. This relationship
+defaults to using the relationship name as the foreign key in C<$related_class>
+to resolve the join, unless C<$join_condition> specifies a column in
+C<$related_class> or a join condition hash reference.
If you update or delete an object in a class with a C<might_have>
relationship, the related object will be updated or deleted as well. To
hashref. Any database-level update or delete constraints will override
this behavior.
+In the above example
+
=head2 has_one
+=over 4
+
+=item Arguments: $accessor_name, $related_class_name, $join_condition?, $attr?
+
+=back
+
My::DBIC::Schema::Book->has_one(isbn => 'My::DBIC::Schema::ISBN');
- my $isbn_obj = $obj->isbn;
+
+ my $isbn_obj = $obj->isbn; # to get the ISBN object
Creates a one-to-one relationship with another class. This is just like
C<might_have>, except the implication is that the other object is always
C<has_one> uses an (ordinary) inner join, whereas C<might_have> uses a
left join.
+The has_one relationship should be used when a row in the table has exactly one
+related row in another table. If the related row might not exist in the foreign
+table, use the L<DBIx::Class::Relationship/might_have> relationship.
+
+In the above example, each Book in the database is associated with exactly one
+ISBN object.
=head2 many_to_many
=over 4
-=item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name
+=item Arguments:
+
+=over 4
+
+=item C<$accessor_name>: The name of the new many_to_many accessor,
+
+=item C<$link_rel_name>: The accessor name of the has_many relationship from
+ the current table to the link table,
+
+=item C<$foreign_rel_name>: The accessor name for the belongs_to relationship
+ from the link table to the foreign table
+
+=item C<$attr>: A hash of relationship attributes for the created many_to_many
+ relationship accessors to use on the C<$foreign_rel_name>.
=back
+=back
+
+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::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' );
+
Creates accessors bridging two relationships; not strictly a relationship in
its own right, although the accessor will return a resultset or collection of
objects just as a has_many would.
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 Role class will have 3 many_to_many accessor methods
+set: C<$roles>, C<$add_to_roles>, C<$set_roles>, and similarly named accessors
+will be created for the Actor class. See L<DBIx::Class::Relationship::Base> for
+more information.
+
=cut
1;
projects / dbsrgits/DBIx-Class.git / commitdiff