Add automatic naming of unique constraints
[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Relationship.pm
CommitLineData
b8e1e21f 1package DBIx::Class::Relationship;
2
3use strict;
4use warnings;
5
1edd1722 6use base qw/DBIx::Class/;
55e2d745 7
07037f89 8__PACKAGE__->load_own_components(qw/
7411204b 9 Helpers
07037f89 10 Accessor
11 CascadeActions
12 ProxyMethods
13 Base
14/);
b8e1e21f 15
75d07914 16=head1 NAME
34d52be2 17
18DBIx::Class::Relationship - Inter-table relationships
19
20=head1 SYNOPSIS
21
75d07914 22 MyDB::Schema::Actor->has_many('actorroles' => 'MyDB::Schema::ActorRole',
d2113a68 23 'actor');
75d07914 24 MyDB::Schema::Role->has_many('actorroles' => 'MyDB::Schema::ActorRole',
d2113a68 25 'role');
26 MyDB::Schema::ActorRole->belongs_to('role' => 'MyDB::Schema::Role');
27 MyDB::Schema::ActorRole->belongs_to('actor' => 'MyDB::Schema::Actor');
28
29 MyDB::Schema::Role->many_to_many('actors' => 'actorroles', 'actor');
30 MyDB::Schema::Actor->many_to_many('roles' => 'actorroles', 'role');
31
32 $schema->resultset('Actor')->roles();
33 $schema->resultset('Role')->search_related('actors', { Name => 'Fred' });
fca27358 34 $schema->resultset('ActorRole')->add_to_roles({ Name => 'Sherlock Holmes'});
d2113a68 35
36See L<DBIx::Class::Manual::Cookbook> for more.
37
34d52be2 38=head1 DESCRIPTION
39
bc1171c3 40This class provides methods to set up relationships between the tables
41in your database model. Relationships are the most useful and powerful
42technique that L<DBIx::Class> provides. To create efficient database queries,
43create relationships between any and all tables that have something in
44common, for example if you have a table Authors:
45
46 ID | Name | Age
47 ------------------
48 1 | Fred | 30
49 2 | Joe | 32
50
51and a table Books:
52
53 ID | Author | Name
54 --------------------
55 1 | 1 | Rulers of the universe
56 2 | 1 | Rulers of the galaxy
57
58Then without relationships, the method of getting all books by Fred goes like
59this:
60
61 my $fred = $schema->resultset('Author')->find({ Name => 'Fred' });
62 my $fredsbooks = $schema->resultset('Book')->search({ Author => $fred->ID });
63With a has_many relationship called "books" on Author (see below for details),
64we can do this instead:
65
66 my $fredsbooks = $schema->resultset('Author')->find({ Name => 'Fred' })->books;
67
75d07914 68Each relationship sets up an accessor method on the
bc1171c3 69L<DBIx::Class::Manual::Glossary/"Row"> objects that represent the items
70of your table. From L<DBIx::Class::Manual::Glossary/"ResultSet"> objects,
75d07914 71the relationships can be searched using the "search_related" method.
bc1171c3 72In list context, each returns a list of Row objects for the related class,
73in scalar context, a new ResultSet representing the joined tables is
74returned. Thus, the calls can be chained to produce complex queries.
75Since the database is not actually queried until you attempt to retrieve
76the data for an actual item, no time is wasted producing them.
77
bc0c9800 78 my $cheapfredbooks = $schema->resultset('Author')->find({
79 Name => 'Fred',
80 })->books->search_related('prices', {
81 Price => { '<=' => '5.00' },
82 });
bc1171c3 83
84will produce a query something like:
85
75d07914 86 SELECT * FROM Author me
bc1171c3 87 LEFT JOIN Books books ON books.author = me.id
88 LEFT JOIN Prices prices ON prices.book = books.id
89 WHERE prices.Price <= 5.00
90
91all without needing multiple fetches.
34d52be2 92
bfab575a 93Only the helper methods for setting up standard relationship types
d2113a68 94are documented here. For the basic, lower-level methods, and a description
95of all the useful *_related methods that you get for free, see
bfab575a 96L<DBIx::Class::Relationship::Base>.
503536d5 97
34d52be2 98=head1 METHODS
99
bfab575a 100All helper methods take the following arguments:
503536d5 101
8091aa91 102 __PACKAGE__>$method_name('relname', 'Foreign::Class', $cond, $attrs);
bfab575a 103
104Both C<$cond> and C<$attrs> are optional. Pass C<undef> for C<$cond> if
105you want to use the default value for it, but still want to set C<$attrs>.
8091aa91 106See L<DBIx::Class::Relationship::Base> for a list of valid attributes.
503536d5 107
bfab575a 108=head2 belongs_to
503536d5 109
c99393ff 110 # in a Book class (where Author has many Books)
d2113a68 111 My::DBIC::Schema::Book->belongs_to(author => 'My::DBIC::Schema::Author');
c99393ff 112 my $author_obj = $obj->author;
113 $obj->author($new_author_obj);
503536d5 114
75d07914 115Creates a relationship where the calling class stores the foreign class's
8091aa91 116primary key in one (or more) of its columns. If $cond is a column name
117instead of a join condition hash, that is used as the name of the column
118holding the foreign key. If $cond is not given, the relname is used as
119the column name.
bfab575a 120
e8e9e5c7 121Cascading deletes are off per default on a C<belongs_to> relationship, to turn
122them on, pass C<< cascade_delete => 1 >> in the $attr hashref.
123
8091aa91 124NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent
125of C<has_a>.
503536d5 126
bfab575a 127=head2 has_many
503536d5 128
c99393ff 129 # in an Author class (where Author has many Books)
d2113a68 130 My::DBIC::Schema::Author->has_many(books => 'My::DBIC::Schema::Book', 'author');
c99393ff 131 my $booklist = $obj->books;
bc0c9800 132 my $booklist = $obj->books({
133 name => { LIKE => '%macaroni%' },
134 { prefetch => [qw/book/],
135 });
c99393ff 136 my @book_objs = $obj->books;
5b89a768 137 my $books_rs = $obj->books;
138 ( $books_rs ) = $obj->books_rs;
503536d5 139
c99393ff 140 $obj->add_to_books(\%col_data);
503536d5 141
8091aa91 142Creates a one-to-many relationship, where the corresponding elements of the
143foreign class store the calling class's primary key in one (or more) of its
144columns. You should pass the name of the column in the foreign class as the
145$cond argument, or specify a complete join condition.
146
60a8fb95 147Three methods are created when you create a has_many relationship. The first
148method is the expected accessor method. The second is almost exactly the same
149as the accessor method but "_rs" is added to the end of the method name. This
150method works just like the normal accessor, except that it returns a resultset
151no matter what, even in list context. The third method, named
152C<< add_to_<relname> >>, will also be added to your Row items, this allows
153you to insert new related items, using the same mechanism as in
5b89a768 154L<DBIx::Class::Relationship::Base/"create_related">.
d2113a68 155
8091aa91 156If you delete an object in a class with a C<has_many> relationship, all
e8e9e5c7 157the related objects will be deleted as well. However, any database-level
158cascade or restrict will take precedence. To turn this behavior off, pass
159C<< cascade_delete => 0 >> in the $attr hashref.
503536d5 160
bfab575a 161=head2 might_have
503536d5 162
75d07914 163 My::DBIC::Schema::Author->might_have(pseudonym =>
d2113a68 164 'My::DBIC::Schema::Pseudonyms');
880a1a0c 165 my $pname = $obj->pseudonym; # to get the Pseudonym object
8091aa91 166
c99393ff 167Creates an optional one-to-one relationship with a class, where the foreign
168class stores our primary key in one of its columns. Defaults to the primary
169key of the foreign class unless $cond specifies a column or join condition.
503536d5 170
c99393ff 171If you update or delete an object in a class with a C<might_have>
172relationship, the related object will be updated or deleted as well.
173Any database-level update or delete constraints will override this behaviour.
e8e9e5c7 174To turn off this behavior, add C<< cascade_delete => 0 >> to the $attr hashref.
503536d5 175
bfab575a 176=head2 has_one
177
d2113a68 178 My::DBIC::Schema::Book->has_one(isbn => 'My::DBIC::Schema::ISBN');
c99393ff 179 my $isbn_obj = $obj->isbn;
bfab575a 180
c99393ff 181Creates a one-to-one relationship with another class. This is just like
182C<might_have>, except the implication is that the other object is always
183present. The only difference between C<has_one> and C<might_have> is that
184C<has_one> uses an (ordinary) inner join, whereas C<might_have> uses a
185left join.
503536d5 186
7411204b 187
87c4e602 188=head2 many_to_many
189
75d07914 190 My::DBIC::Schema::Actor->has_many( actor_roles =>
d2113a68 191 'My::DBIC::Schema::ActorRoles',
192 'actor' );
75d07914 193 My::DBIC::Schema::ActorRoles->belongs_to( role =>
d2113a68 194 'My::DBIC::Schema::Role' );
75d07914 195 My::DBIC::Schema::ActorRoles->belongs_to( actor =>
d2113a68 196 'My::DBIC::Schema::Actor' );
197
198 My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles',
71d5ed18 199 'role' );
bc0c9800 200
201 ...
202
203 my @role_objs = $actor->roles;
b8eca5ce 204
205Creates an accessor bridging two relationships; not strictly a relationship
206in its own right, although the accessor will return a resultset or collection
207of objects just as a has_many would.
d2113a68 208To use many_to_many, existing relationships from the original table to the link
75d07914 209table, and from the link table to the end table must already exist, these
d2113a68 210relation names are then used in the many_to_many call.
7411204b 211
34d52be2 212=cut
213
b8e1e21f 2141;
34d52be2 215
34d52be2 216=head1 AUTHORS
217
daec44b8 218Matt S. Trout <mst@shadowcatsystems.co.uk>
34d52be2 219
220=head1 LICENSE
221
222You may distribute this code under the same terms as Perl itself.
223
224=cut
225