Commit | Line | Data |
b8e1e21f |
1 | package DBIx::Class::Relationship; |
2 | |
3 | use strict; |
4 | use warnings; |
5 | |
1edd1722 |
6 | use 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 | |
34d52be2 |
16 | =head1 NAME |
17 | |
18 | DBIx::Class::Relationship - Inter-table relationships |
19 | |
20 | =head1 SYNOPSIS |
21 | |
22 | =head1 DESCRIPTION |
23 | |
bc1171c3 |
24 | This class provides methods to set up relationships between the tables |
25 | in your database model. Relationships are the most useful and powerful |
26 | technique that L<DBIx::Class> provides. To create efficient database queries, |
27 | create relationships between any and all tables that have something in |
28 | common, for example if you have a table Authors: |
29 | |
30 | ID | Name | Age |
31 | ------------------ |
32 | 1 | Fred | 30 |
33 | 2 | Joe | 32 |
34 | |
35 | and a table Books: |
36 | |
37 | ID | Author | Name |
38 | -------------------- |
39 | 1 | 1 | Rulers of the universe |
40 | 2 | 1 | Rulers of the galaxy |
41 | |
42 | Then without relationships, the method of getting all books by Fred goes like |
43 | this: |
44 | |
45 | my $fred = $schema->resultset('Author')->find({ Name => 'Fred' }); |
46 | my $fredsbooks = $schema->resultset('Book')->search({ Author => $fred->ID }); |
47 | With a has_many relationship called "books" on Author (see below for details), |
48 | we can do this instead: |
49 | |
50 | my $fredsbooks = $schema->resultset('Author')->find({ Name => 'Fred' })->books; |
51 | |
52 | Each relationship sets up an accessor method on the |
53 | L<DBIx::Class::Manual::Glossary/"Row"> objects that represent the items |
54 | of your table. From L<DBIx::Class::Manual::Glossary/"ResultSet"> objects, |
55 | the relationships can be searched using the "search_related" method. |
56 | In list context, each returns a list of Row objects for the related class, |
57 | in scalar context, a new ResultSet representing the joined tables is |
58 | returned. Thus, the calls can be chained to produce complex queries. |
59 | Since the database is not actually queried until you attempt to retrieve |
60 | the data for an actual item, no time is wasted producing them. |
61 | |
bc0c9800 |
62 | my $cheapfredbooks = $schema->resultset('Author')->find({ |
63 | Name => 'Fred', |
64 | })->books->search_related('prices', { |
65 | Price => { '<=' => '5.00' }, |
66 | }); |
bc1171c3 |
67 | |
68 | will produce a query something like: |
69 | |
70 | SELECT * FROM Author me |
71 | LEFT JOIN Books books ON books.author = me.id |
72 | LEFT JOIN Prices prices ON prices.book = books.id |
73 | WHERE prices.Price <= 5.00 |
74 | |
75 | all without needing multiple fetches. |
34d52be2 |
76 | |
bfab575a |
77 | Only the helper methods for setting up standard relationship types |
78 | are documented here. For the basic, lower-level methods, see |
79 | L<DBIx::Class::Relationship::Base>. |
503536d5 |
80 | |
34d52be2 |
81 | =head1 METHODS |
82 | |
bfab575a |
83 | All helper methods take the following arguments: |
503536d5 |
84 | |
8091aa91 |
85 | __PACKAGE__>$method_name('relname', 'Foreign::Class', $cond, $attrs); |
bfab575a |
86 | |
87 | Both C<$cond> and C<$attrs> are optional. Pass C<undef> for C<$cond> if |
88 | you want to use the default value for it, but still want to set C<$attrs>. |
8091aa91 |
89 | See L<DBIx::Class::Relationship::Base> for a list of valid attributes. |
503536d5 |
90 | |
bfab575a |
91 | =head2 belongs_to |
503536d5 |
92 | |
c99393ff |
93 | # in a Book class (where Author has many Books) |
94 | My::DBIC::Schema::Book->belongs_to(author => 'Author'); |
95 | my $author_obj = $obj->author; |
96 | $obj->author($new_author_obj); |
503536d5 |
97 | |
8091aa91 |
98 | Creates a relationship where the calling class stores the foreign class's |
99 | primary key in one (or more) of its columns. If $cond is a column name |
100 | instead of a join condition hash, that is used as the name of the column |
101 | holding the foreign key. If $cond is not given, the relname is used as |
102 | the column name. |
bfab575a |
103 | |
8091aa91 |
104 | NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent |
105 | of C<has_a>. |
503536d5 |
106 | |
bfab575a |
107 | =head2 has_many |
503536d5 |
108 | |
c99393ff |
109 | # in an Author class (where Author has many Books) |
110 | My::DBIC::Schema::Author->has_many(books => 'Book', 'author'); |
111 | my $booklist = $obj->books; |
bc0c9800 |
112 | my $booklist = $obj->books({ |
113 | name => { LIKE => '%macaroni%' }, |
114 | { prefetch => [qw/book/], |
115 | }); |
c99393ff |
116 | my @book_objs = $obj->books; |
503536d5 |
117 | |
c99393ff |
118 | $obj->add_to_books(\%col_data); |
503536d5 |
119 | |
8091aa91 |
120 | Creates a one-to-many relationship, where the corresponding elements of the |
121 | foreign class store the calling class's primary key in one (or more) of its |
122 | columns. You should pass the name of the column in the foreign class as the |
123 | $cond argument, or specify a complete join condition. |
124 | |
125 | If you delete an object in a class with a C<has_many> relationship, all |
126 | related objects will be deleted as well. However, any database-level |
127 | cascade or restrict will take precedence. |
503536d5 |
128 | |
bfab575a |
129 | =head2 might_have |
503536d5 |
130 | |
c99393ff |
131 | My::DBIC::Schema::Author->might_have(psuedonym => 'Psuedonyms'); |
132 | my $pname = $obj->psuedonym; # to get the Psuedonym object |
8091aa91 |
133 | |
c99393ff |
134 | Creates an optional one-to-one relationship with a class, where the foreign |
135 | class stores our primary key in one of its columns. Defaults to the primary |
136 | key of the foreign class unless $cond specifies a column or join condition. |
503536d5 |
137 | |
c99393ff |
138 | If you update or delete an object in a class with a C<might_have> |
139 | relationship, the related object will be updated or deleted as well. |
140 | Any database-level update or delete constraints will override this behaviour. |
503536d5 |
141 | |
bfab575a |
142 | =head2 has_one |
143 | |
c99393ff |
144 | My::DBIC::Schema::Book->has_one(isbn => ISBN); |
145 | my $isbn_obj = $obj->isbn; |
bfab575a |
146 | |
c99393ff |
147 | Creates a one-to-one relationship with another class. This is just like |
148 | C<might_have>, except the implication is that the other object is always |
149 | present. The only difference between C<has_one> and C<might_have> is that |
150 | C<has_one> uses an (ordinary) inner join, whereas C<might_have> uses a |
151 | left join. |
503536d5 |
152 | |
7411204b |
153 | |
87c4e602 |
154 | =head2 many_to_many |
155 | |
c99393ff |
156 | My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles', 'Roles' ); |
bc0c9800 |
157 | |
158 | ... |
159 | |
160 | my @role_objs = $actor->roles; |
b8eca5ce |
161 | |
162 | Creates an accessor bridging two relationships; not strictly a relationship |
163 | in its own right, although the accessor will return a resultset or collection |
164 | of objects just as a has_many would. |
7411204b |
165 | |
34d52be2 |
166 | =cut |
167 | |
b8e1e21f |
168 | 1; |
34d52be2 |
169 | |
34d52be2 |
170 | =head1 AUTHORS |
171 | |
daec44b8 |
172 | Matt S. Trout <mst@shadowcatsystems.co.uk> |
34d52be2 |
173 | |
174 | =head1 LICENSE |
175 | |
176 | You may distribute this code under the same terms as Perl itself. |
177 | |
178 | =cut |
179 | |