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 | |
62 | my $cheapfredbooks = $schema->resultset('Author')->find({ Name => 'Fred' })->books->search_related('prices', { Price => { '<=' => '5.00' } }); |
63 | |
64 | will produce a query something like: |
65 | |
66 | SELECT * FROM Author me |
67 | LEFT JOIN Books books ON books.author = me.id |
68 | LEFT JOIN Prices prices ON prices.book = books.id |
69 | WHERE prices.Price <= 5.00 |
70 | |
71 | all without needing multiple fetches. |
34d52be2 |
72 | |
bfab575a |
73 | Only the helper methods for setting up standard relationship types |
74 | are documented here. For the basic, lower-level methods, see |
75 | L<DBIx::Class::Relationship::Base>. |
503536d5 |
76 | |
34d52be2 |
77 | =head1 METHODS |
78 | |
bfab575a |
79 | All helper methods take the following arguments: |
503536d5 |
80 | |
8091aa91 |
81 | __PACKAGE__>$method_name('relname', 'Foreign::Class', $cond, $attrs); |
bfab575a |
82 | |
83 | Both C<$cond> and C<$attrs> are optional. Pass C<undef> for C<$cond> if |
84 | you want to use the default value for it, but still want to set C<$attrs>. |
8091aa91 |
85 | See L<DBIx::Class::Relationship::Base> for a list of valid attributes. |
503536d5 |
86 | |
bfab575a |
87 | =head2 belongs_to |
503536d5 |
88 | |
c99393ff |
89 | # in a Book class (where Author has many Books) |
90 | My::DBIC::Schema::Book->belongs_to(author => 'Author'); |
91 | my $author_obj = $obj->author; |
92 | $obj->author($new_author_obj); |
503536d5 |
93 | |
8091aa91 |
94 | Creates a relationship where the calling class stores the foreign class's |
95 | primary key in one (or more) of its columns. If $cond is a column name |
96 | instead of a join condition hash, that is used as the name of the column |
97 | holding the foreign key. If $cond is not given, the relname is used as |
98 | the column name. |
bfab575a |
99 | |
8091aa91 |
100 | NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent |
101 | of C<has_a>. |
503536d5 |
102 | |
bfab575a |
103 | =head2 has_many |
503536d5 |
104 | |
c99393ff |
105 | # in an Author class (where Author has many Books) |
106 | My::DBIC::Schema::Author->has_many(books => 'Book', 'author'); |
107 | my $booklist = $obj->books; |
108 | my $booklist = $obj->books({ name => { LIKE => '%macaroni%' }, { prefetch => [qw/book/] }); |
109 | my @book_objs = $obj->books; |
503536d5 |
110 | |
c99393ff |
111 | $obj->add_to_books(\%col_data); |
503536d5 |
112 | |
8091aa91 |
113 | Creates a one-to-many relationship, where the corresponding elements of the |
114 | foreign class store the calling class's primary key in one (or more) of its |
115 | columns. You should pass the name of the column in the foreign class as the |
116 | $cond argument, or specify a complete join condition. |
117 | |
118 | If you delete an object in a class with a C<has_many> relationship, all |
119 | related objects will be deleted as well. However, any database-level |
120 | cascade or restrict will take precedence. |
503536d5 |
121 | |
bfab575a |
122 | =head2 might_have |
503536d5 |
123 | |
c99393ff |
124 | My::DBIC::Schema::Author->might_have(psuedonym => 'Psuedonyms'); |
125 | my $pname = $obj->psuedonym; # to get the Psuedonym object |
8091aa91 |
126 | |
c99393ff |
127 | Creates an optional one-to-one relationship with a class, where the foreign |
128 | class stores our primary key in one of its columns. Defaults to the primary |
129 | key of the foreign class unless $cond specifies a column or join condition. |
503536d5 |
130 | |
c99393ff |
131 | If you update or delete an object in a class with a C<might_have> |
132 | relationship, the related object will be updated or deleted as well. |
133 | Any database-level update or delete constraints will override this behaviour. |
503536d5 |
134 | |
bfab575a |
135 | =head2 has_one |
136 | |
c99393ff |
137 | My::DBIC::Schema::Book->has_one(isbn => ISBN); |
138 | my $isbn_obj = $obj->isbn; |
bfab575a |
139 | |
c99393ff |
140 | Creates a one-to-one relationship with another class. This is just like |
141 | C<might_have>, except the implication is that the other object is always |
142 | present. The only difference between C<has_one> and C<might_have> is that |
143 | C<has_one> uses an (ordinary) inner join, whereas C<might_have> uses a |
144 | left join. |
503536d5 |
145 | |
7411204b |
146 | |
87c4e602 |
147 | =head2 many_to_many |
148 | |
c99393ff |
149 | My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles', 'Roles' ); |
150 | my @role_objs = $obj_a->roles; |
b8eca5ce |
151 | |
152 | Creates an accessor bridging two relationships; not strictly a relationship |
153 | in its own right, although the accessor will return a resultset or collection |
154 | of objects just as a has_many would. |
7411204b |
155 | |
34d52be2 |
156 | =cut |
157 | |
b8e1e21f |
158 | 1; |
34d52be2 |
159 | |
34d52be2 |
160 | =head1 AUTHORS |
161 | |
daec44b8 |
162 | Matt S. Trout <mst@shadowcatsystems.co.uk> |
34d52be2 |
163 | |
164 | =head1 LICENSE |
165 | |
166 | You may distribute this code under the same terms as Perl itself. |
167 | |
168 | =cut |
169 | |