1DBIx::Class::RelationshUispe:r:BCaosnet(r3i)buted Perl DDoBcIuxm:e:nCtlaatsiso:n:Relationship::Base(3)
2
6 DBIx::Class::Relationship::Base - Inter-table relationships
7
10 This class provides methods to describe the relationships between the
11 tables in your database model. These are the "bare bones" relationships
12 methods, for predefined ones, look in DBIx::Class::Relationship.
13
15 add_relationship
16 Arguments: 'relname', 'Foreign::Class', $cond, $attrs
17 __PACKAGE__->add_relationship('relname', 'Foreign::Class', $cond, $attrs);
19 condition
21 The condition needs to be an SQL::Abstract-style representation of the
23 join between the tables. When resolving the condition for use in a
24 "JOIN", keys using the pseudo-table "foreign" are resolved to mean "the
25 Table on the other side of the relationship", and values using the
26 pseudo-table "self" are resolved to mean "the Table this class is
27 representing". Other restrictions, such as by value, sub-select and
28 other tables, may also be used. Please check your database for "JOIN"
29 parameter support.
30 For example, if you're creating a relationship from "Author" to "Book",
32 where the "Book" table has a column "author_id" containing the ID of
33 the "Author" row:
34 { 'foreign.author_id' => 'self.id' }
36 will result in the "JOIN" clause
38 author me JOIN book book ON book.author_id = me.id
40 For multi-column foreign keys, you will need to specify a
42 "foreign"-to-"self" mapping for each column in the key. For example, if
43 you're creating a relationship from "Book" to "Edition", where the
44 "Edition" table refers to a publisher and a type (e.g. "paperback"):
45 {
47 'foreign.publisher_id' => 'self.publisher_id',
48 'foreign.type_id' => 'self.type_id',
49 }
50 This will result in the "JOIN" clause:
52 book me JOIN edition edition ON edition.publisher_id = me.publisher_id
54 AND edition.type_id = me.type_id
55 Each key-value pair provided in a hashref will be used as "AND"ed
57 conditions. To add an "OR"ed condition, use an arrayref of hashrefs.
58 See the SQL::Abstract documentation for more details.
59 attributes
61 The standard ResultSet attributes may be used as relationship
63 attributes. In particular, the 'where' attribute is useful for
64 filtering relationships:
65 __PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User',
67 { 'foreign.user_id' => 'self.user_id' },
68 { where => { valid => 1 } }
69 );
70 The following attributes are also valid:
72 join_type
74 Explicitly specifies the type of join to use in the relationship.
75 Any SQL join type is valid, e.g. "LEFT" or "RIGHT". It will be
76 placed in the SQL command immediately before "JOIN".
77 proxy
79 An arrayref containing a list of accessors in the foreign class to
80 create in the main class. If, for example, you do the following:
81 MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes',
83 undef, {
84 proxy => [ qw/notes/ ],
85 });
86 Then, assuming MyDB::Schema::LinerNotes has an accessor named
88 notes, you can do:
89 my $cd = MyDB::Schema::CD->find(1);
91 $cd->notes('Notes go here'); # set notes -- LinerNotes object is
92 # created if it doesn't exist
93 accessor
95 Specifies the type of accessor that should be created for the
96 relationship. Valid values are "single" (for when there is only a
97 single related object), "multi" (when there can be many), and
98 "filter" (for when there is a single related object, but you also
99 want the relationship accessor to double as a column accessor). For
100 "multi" accessors, an add_to_* method is also created, which calls
101 "create_related" for the relationship.
102 is_foreign_key_constraint
104 If you are using SQL::Translator to create SQL for you and you find
105 that it is creating constraints where it shouldn't, or not creating
106 them where it should, set this attribute to a true or false value
107 to override the detection of when to create constraints.
108 on_delete / on_update
110 If you are using SQL::Translator to create SQL for you, you can use
111 these attributes to explicitly set the desired "ON DELETE" or "ON
112 UPDATE" constraint type. If not supplied the SQLT parser will
113 attempt to infer the constraint type by interrogating the
114 attributes of the opposite relationship. For any 'multi'
115 relationship with "cascade_delete => 1", the corresponding
116 belongs_to relationship will be created with an "ON DELETE CASCADE"
117 constraint. For any relationship bearing "cascade_copy => 1" the
118 resulting belongs_to constraint will be "ON UPDATE CASCADE". If you
119 wish to disable this autodetection, and just use the RDBMS' default
120 constraint type, pass "on_delete => undef" or "on_delete => ''",
121 and the same for "on_update" respectively.
122 is_deferrable
124 Tells SQL::Translator that the foreign key constraint it creates
125 should be deferrable. In other words, the user may request that the
126 constraint be ignored until the end of the transaction. Currently,
127 only the PostgreSQL producer actually supports this.
128 add_fk_index
130 Tells SQL::Translator to add an index for this constraint. Can also
131 be specified globally in the args to "deploy" in
132 DBIx::Class::Schema or "create_ddl_dir" in DBIx::Class::Schema.
133 Default is on, set to 0 to disable.
134 register_relationship
136 Arguments: $relname, $rel_info
137 Registers a relationship on the class. This is called internally by
139 DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
140 related_resultset
142 Arguments: $relationship_name
143 Return Value: $related_resultset
144 $rs = $cd->related_resultset('artist');
146 Returns a DBIx::Class::ResultSet for the relationship named
148 $relationship_name.
149 search_related
151 @objects = $rs->search_related('relname', $cond, $attrs);
152 $objects_rs = $rs->search_related('relname', $cond, $attrs);
153 Run a search on a related resultset. The search will be restricted to
155 the item or items represented by the DBIx::Class::ResultSet it was
156 called upon. This method can be called on a ResultSet, a Row or a
157 ResultSource class.
158 search_related_rs
160 ( $objects_rs ) = $rs->search_related_rs('relname', $cond, $attrs);
161 This method works exactly the same as search_related, except that it
163 guarantees a resultset, even in list context.
164 count_related
166 $obj->count_related('relname', $cond, $attrs);
167 Returns the count of all the items in the related resultset, restricted
169 by the current item or where conditions. Can be called on a "ResultSet"
170 in DBIx::Class::Manual::Glossary or a "Row" in
171 DBIx::Class::Manual::Glossary object.
172 new_related
174 my $new_obj = $obj->new_related('relname', \%col_data);
175 Create a new item of the related foreign class. If called on a Row
177 object, it will magically set any foreign key columns of the new object
178 to the related primary key columns of the source object for you. The
179 newly created item will not be saved into your storage until you call
180 "insert" in DBIx::Class::Row on it.
181 create_related
183 my $new_obj = $obj->create_related('relname', \%col_data);
184 Creates a new item, similarly to new_related, and also inserts the
186 item's data into your storage medium. See the distinction between
187 "create" and "new" in DBIx::Class::ResultSet for details.
188 find_related
190 my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals);
191 Attempt to find a related object using its primary key or unique
193 constraints. See "find" in DBIx::Class::ResultSet for details.
194 find_or_new_related
196 my $new_obj = $obj->find_or_new_related('relname', \%col_data);
197 Find an item of a related class. If none exists, instantiate a new item
199 of the related class. The object will not be saved into your storage
200 until you call "insert" in DBIx::Class::Row on it.
201 find_or_create_related
203 my $new_obj = $obj->find_or_create_related('relname', \%col_data);
204 Find or create an item of a related class. See "find_or_create" in
206 DBIx::Class::ResultSet for details.
207 update_or_create_related
209 my $updated_item = $obj->update_or_create_related('relname', \%col_data, \%attrs?);
210 Update or create an item of a related class. See "update_or_create" in
212 DBIx::Class::ResultSet for details.
213 set_from_related
215 $book->set_from_related('author', $author_obj);
216 $book->author($author_obj); ## same thing
217 Set column values on the current object, using related values from the
219 given related object. This is used to associate previously separate
220 objects, for example, to set the correct author for a book, find the
221 Author object, then call set_from_related on the book.
222 This is called internally when you pass existing objects as values to
224 "create" in DBIx::Class::ResultSet, or pass an object to a belongs_to
225 accessor.
226 The columns are only set in the local copy of the object, call "update"
228 to set them in the storage.
229 update_from_related
231 $book->update_from_related('author', $author_obj);
232 The same as "set_from_related", but the changes are immediately updated
234 in storage.
235 delete_related
237 $obj->delete_related('relname', $cond, $attrs);
238 Delete any related item subject to the given conditions.
240 add_to_$rel
242 Currently only available for "has_many", "many-to-many" and 'multi'
243 type relationships.
244 Arguments: ($foreign_vals | $obj), $link_vals?
246 my $role = $schema->resultset('Role')->find(1);
248 $actor->add_to_roles($role);
249 # creates a My::DBIC::Schema::ActorRoles linking table row object
250 $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
252 # creates a new My::DBIC::Schema::Role row object and the linking table
253 # object with an extra column in the link
254 Adds a linking table object for $obj or $foreign_vals. If the first
256 argument is a hash reference, the related object is created first with
257 the column values in the hash. If an object reference is given, just
258 the linking table object is created. In either case, any additional
259 column values for the linking table object can be specified in
260 $link_vals.
261 set_$rel
263 Currently only available for "many-to-many" relationships.
264 Arguments: (\@hashrefs | \@objs), $link_vals?
266 my $actor = $schema->resultset('Actor')->find(1);
268 my @roles = $schema->resultset('Role')->search({ role =>
269 { '-in' => ['Fred', 'Barney'] } } );
270 $actor->set_roles(\@roles);
272 # Replaces all of $actor's previous roles with the two named
273 $actor->set_roles(\@roles, { salary => 15_000_000 });
275 # Sets a column in the link table for all roles
276 Replace all the related objects with the given reference to a list of
278 objects. This does a "delete" on the link table resultset to remove the
279 association between the current object and all related objects, then
280 calls "add_to_$rel" repeatedly to link all the new objects.
281 Note that this means that this method will not delete any objects in
283 the table on the right side of the relation, merely that it will delete
284 the link between them.
285 Due to a mistake in the original implementation of this method, it will
287 also accept a list of objects or hash references. This is deprecated
288 and will be removed in a future version.
289 remove_from_$rel
291 Currently only available for "many-to-many" relationships.
292 Arguments: $obj
294 my $role = $schema->resultset('Role')->find(1);
296 $actor->remove_from_roles($role);
297 # removes $role's My::DBIC::Schema::ActorRoles linking table row object
298 Removes the link between the current object and the related object.
300 Note that the related object itself won't be deleted unless you call
301 ->delete() on it. This method just removes the link between the two
302 objects.
303
305 Matt S. Trout <mst@shadowcatsystems.co.uk>
306
308 You may distribute this code under the same terms as Perl itself.
309perl v5.12.0 2010-05-12DBIx::Class::Relationship::Base(3)