remove_columns now deletes columns from _columns fixing has_columns false positives
[dbsrgits/DBIx-Class-Historic.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
b8810cc5 116primary key in one (or more) of its columns. If C<$cond> is a column name
8091aa91 117instead of a join condition hash, that is used as the name of the column
b8810cc5 118holding the foreign key. If C<$cond> is not given, the relname is used as
8091aa91 119the column name.
bfab575a 120
b8810cc5 121If the relationship is optional - i.e. the column containing the foreign
2c3ad870 122key can be NULL - then the belongs_to relationship does the right
b8810cc5 123thing - so in the example above C<$obj-E<gt>author> would return C<undef>.
2c3ad870 124However in this case you would probably want to set the C<join_type>
125attribute so that a C<LEFT JOIN> is done, which makes complex
126resultsets involving C<join> or C<prefetch> operations work correctly.
b8810cc5 127The modified declaration is shown below:
2c3ad870 128
b8810cc5 129 # in a Book class (where Author has_many Books)
2c3ad870 130 __PACKAGE__->belongs_to(author => 'My::DBIC::Schema::Author',
131 'author', {join_type => 'left'});
132
133
b8810cc5 134Cascading deletes are off by default on a C<belongs_to>
135relationship. To turn them on, pass C<< cascade_delete => 1 >>
136in the $attr hashref.
e8e9e5c7 137
8091aa91 138NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent
139of C<has_a>.
503536d5 140
bfab575a 141=head2 has_many
503536d5 142
b8810cc5 143 # in an Author class (where Author has_many Books)
d2113a68 144 My::DBIC::Schema::Author->has_many(books => 'My::DBIC::Schema::Book', 'author');
c99393ff 145 my $booklist = $obj->books;
bc0c9800 146 my $booklist = $obj->books({
147 name => { LIKE => '%macaroni%' },
148 { prefetch => [qw/book/],
149 });
c99393ff 150 my @book_objs = $obj->books;
5b89a768 151 my $books_rs = $obj->books;
152 ( $books_rs ) = $obj->books_rs;
503536d5 153
c99393ff 154 $obj->add_to_books(\%col_data);
503536d5 155
8091aa91 156Creates a one-to-many relationship, where the corresponding elements of the
157foreign class store the calling class's primary key in one (or more) of its
158columns. You should pass the name of the column in the foreign class as the
b8810cc5 159C<$cond> argument, or specify a complete join condition.
8091aa91 160
60a8fb95 161Three methods are created when you create a has_many relationship. The first
162method is the expected accessor method. The second is almost exactly the same
163as the accessor method but "_rs" is added to the end of the method name. This
164method works just like the normal accessor, except that it returns a resultset
165no matter what, even in list context. The third method, named
b8810cc5 166C<< add_to_<relname> >>, will also be added to your Row items; this allows
60a8fb95 167you to insert new related items, using the same mechanism as in
5b89a768 168L<DBIx::Class::Relationship::Base/"create_related">.
d2113a68 169
8091aa91 170If you delete an object in a class with a C<has_many> relationship, all
b8810cc5 171the related objects will be deleted as well. To turn this behaviour off,
172pass C<< cascade_delete => 0 >> in the C<$attr> hashref. However, any
173database-level cascade or restrict will take precedence over a
174DBIx-Class-based cascading delete.
503536d5 175
bfab575a 176=head2 might_have
503536d5 177
75d07914 178 My::DBIC::Schema::Author->might_have(pseudonym =>
d2113a68 179 'My::DBIC::Schema::Pseudonyms');
880a1a0c 180 my $pname = $obj->pseudonym; # to get the Pseudonym object
8091aa91 181
c99393ff 182Creates an optional one-to-one relationship with a class, where the foreign
183class stores our primary key in one of its columns. Defaults to the primary
b8810cc5 184key of the foreign class unless C<$cond> specifies a column or join condition.
503536d5 185
c99393ff 186If you update or delete an object in a class with a C<might_have>
b8810cc5 187relationship, the related object will be updated or deleted as well. To
188turn off this behavior, add C<< cascade_delete => 0 >> to the C<$attr>
189hashref. Any database-level update or delete constraints will override
190this behavior.
503536d5 191
bfab575a 192=head2 has_one
193
d2113a68 194 My::DBIC::Schema::Book->has_one(isbn => 'My::DBIC::Schema::ISBN');
c99393ff 195 my $isbn_obj = $obj->isbn;
bfab575a 196
c99393ff 197Creates a one-to-one relationship with another class. This is just like
198C<might_have>, except the implication is that the other object is always
199present. The only difference between C<has_one> and C<might_have> is that
200C<has_one> uses an (ordinary) inner join, whereas C<might_have> uses a
201left join.
503536d5 202
7411204b 203
87c4e602 204=head2 many_to_many
205
303cf522 206=over 4
207
208=item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name
209
210=back
211
75d07914 212 My::DBIC::Schema::Actor->has_many( actor_roles =>
d2113a68 213 'My::DBIC::Schema::ActorRoles',
214 'actor' );
75d07914 215 My::DBIC::Schema::ActorRoles->belongs_to( role =>
d2113a68 216 'My::DBIC::Schema::Role' );
75d07914 217 My::DBIC::Schema::ActorRoles->belongs_to( actor =>
d2113a68 218 'My::DBIC::Schema::Actor' );
219
220 My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles',
71d5ed18 221 'role' );
bc0c9800 222
b8810cc5 223Creates accessors bridging two relationships; not strictly a relationship in
303cf522 224its own right, although the accessor will return a resultset or collection of
225objects just as a has_many would.
b8eca5ce 226
d2113a68 227To use many_to_many, existing relationships from the original table to the link
75d07914 228table, and from the link table to the end table must already exist, these
d2113a68 229relation names are then used in the many_to_many call.
7411204b 230
34d52be2 231=cut
232
b8e1e21f 2331;
34d52be2 234
34d52be2 235=head1 AUTHORS
236
daec44b8 237Matt S. Trout <mst@shadowcatsystems.co.uk>
34d52be2 238
239=head1 LICENSE
240
241You may distribute this code under the same terms as Perl itself.
242
243=cut
244