Consider unselected order_by during complex subqueried prefetch
[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
951ab5ab 22 ## Creating relationships
03460bef 23 MyApp::Schema::Actor->has_many('actorroles' => 'MyApp::Schema::ActorRole',
d2113a68 24 'actor');
03460bef 25 MyApp::Schema::Role->has_many('actorroles' => 'MyApp::Schema::ActorRole',
d2113a68 26 'role');
03460bef 27 MyApp::Schema::ActorRole->belongs_to('role' => 'MyApp::Schema::Role');
28 MyApp::Schema::ActorRole->belongs_to('actor' => 'MyApp::Schema::Actor');
d2113a68 29
03460bef 30 MyApp::Schema::Role->many_to_many('actors' => 'actorroles', 'actor');
31 MyApp::Schema::Actor->many_to_many('roles' => 'actorroles', 'role');
d2113a68 32
951ab5ab 33 ## Using relationships
c9070342 34 $schema->resultset('Actor')->find({ id => 1})->roles();
35 $schema->resultset('Role')->find({ id => 1 })->actorroles->search_related('actor', { Name => 'Fred' });
36 $schema->resultset('Actor')->add_to_roles({ Name => 'Sherlock Holmes'});
d2113a68 37
38See L<DBIx::Class::Manual::Cookbook> for more.
39
34d52be2 40=head1 DESCRIPTION
41
7cf4ae7a 42The word I<Relationship> has a specific meaning in DBIx::Class, see
43the definition in the L<Glossary|DBIx::Class::Manual::Glossary/Relationship>.
44
bc1171c3 45This class provides methods to set up relationships between the tables
46in your database model. Relationships are the most useful and powerful
47technique that L<DBIx::Class> provides. To create efficient database queries,
48create relationships between any and all tables that have something in
49common, for example if you have a table Authors:
50
51 ID | Name | Age
52 ------------------
53 1 | Fred | 30
54 2 | Joe | 32
55
56and a table Books:
57
58 ID | Author | Name
59 --------------------
60 1 | 1 | Rulers of the universe
61 2 | 1 | Rulers of the galaxy
62
63Then without relationships, the method of getting all books by Fred goes like
64this:
65
66 my $fred = $schema->resultset('Author')->find({ Name => 'Fred' });
67 my $fredsbooks = $schema->resultset('Book')->search({ Author => $fred->ID });
2f0790c4 68
bc1171c3 69With a has_many relationship called "books" on Author (see below for details),
70we can do this instead:
71
72 my $fredsbooks = $schema->resultset('Author')->find({ Name => 'Fred' })->books;
73
75d07914 74Each relationship sets up an accessor method on the
bc1171c3 75L<DBIx::Class::Manual::Glossary/"Row"> objects that represent the items
76of your table. From L<DBIx::Class::Manual::Glossary/"ResultSet"> objects,
75d07914 77the relationships can be searched using the "search_related" method.
fb13a49f 78In list context, each returns a list of Result objects for the related class,
bc1171c3 79in scalar context, a new ResultSet representing the joined tables is
80returned. Thus, the calls can be chained to produce complex queries.
81Since the database is not actually queried until you attempt to retrieve
82the data for an actual item, no time is wasted producing them.
83
bc0c9800 84 my $cheapfredbooks = $schema->resultset('Author')->find({
85 Name => 'Fred',
86 })->books->search_related('prices', {
87 Price => { '<=' => '5.00' },
88 });
bc1171c3 89
90will produce a query something like:
91
75d07914 92 SELECT * FROM Author me
bc1171c3 93 LEFT JOIN Books books ON books.author = me.id
94 LEFT JOIN Prices prices ON prices.book = books.id
95 WHERE prices.Price <= 5.00
96
97all without needing multiple fetches.
34d52be2 98
bfab575a 99Only the helper methods for setting up standard relationship types
d2113a68 100are documented here. For the basic, lower-level methods, and a description
101of all the useful *_related methods that you get for free, see
bfab575a 102L<DBIx::Class::Relationship::Base>.
503536d5 103
34d52be2 104=head1 METHODS
105
8457faf7 106All helper methods are called similar to the following template:
503536d5 107
6c4f4d69 108 __PACKAGE__->$method_name('relname', 'Foreign::Class', \%cond|\@cond|\&cond?, \%attrs?);
d4daee7b 109
13523f29 110Both C<cond> and C<attrs> are optional. Pass C<undef> for C<cond> if
111you want to use the default value for it, but still want to set C<attrs>.
2535b501 112
6c4f4d69 113See L<DBIx::Class::Relationship::Base/condition> for full documentation on
114definition of the C<cond> argument.
13523f29 115
116See L<DBIx::Class::Relationship::Base/attributes> for documentation on the
117attributes that are allowed in the C<attrs> argument.
8457faf7 118
503536d5 119
bfab575a 120=head2 belongs_to
503536d5 121
2f3105ce 122=over 4
123
13523f29 124=item Arguments: $accessor_name, $related_class, $our_fk_column|\%cond|\@cond|\$cond?, \%attrs?
2f3105ce 125
126=back
127
951ab5ab 128Creates a relationship where the calling class stores the foreign
b0acf5d8 129class's primary key in one (or more) of the calling class columns.
130This relationship defaults to using C<$accessor_name> as the column
131name in this class to resolve the join against the primary key from
132C<$related_class>, unless C<$our_fk_column> specifies the foreign key column
13523f29 133in this class or C<cond> specifies a reference to a join condition.
7a2c1380 134
135=over
136
137=item accessor_name
138
139This argument is the name of the method you can call on a
fb13a49f 140L<Result|DBIx::Class::Manual::ResultClass> object to retrieve the instance of the foreign
8457faf7 141class matching this relationship. This is often called the
142C<relation(ship) name>.
7a2c1380 143
8457faf7 144Use this accessor_name in L<DBIx::Class::ResultSet/join>
7a2c1380 145or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
146indicated by this relationship.
147
148=item related_class
149
150This is the class name of the table referenced by the foreign key in
151this class.
152
b0acf5d8 153=item our_fk_column
7a2c1380 154
155The column name on this class that contains the foreign key.
156
157OR
158
159=item cond
160
13523f29 161A hashref, arrayref or coderef specifying a custom join expression. For
6c30f9c3 162more info see L<DBIx::Class::Relationship::Base/condition>.
7a2c1380 163
164=back
165
c99393ff 166 # in a Book class (where Author has many Books)
8273e845 167 My::DBIC::Schema::Book->belongs_to(
168 author =>
169 'My::DBIC::Schema::Author',
951ab5ab 170 'author_id'
171 );
172
173 # OR (same result)
174 My::DBIC::Schema::Book->belongs_to(
175 author =>
176 'My::DBIC::Schema::Author',
8273e845 177 { 'foreign.author_id' => 'self.author_id' }
951ab5ab 178 );
179
180 # OR (similar result but uglier accessor name)
8273e845 181 My::DBIC::Schema::Book->belongs_to(
951ab5ab 182 author_id =>
183 'My::DBIC::Schema::Author'
184 );
185
186 # Usage
187 my $author_obj = $book->author; # get author object
188 $book->author( $new_author_obj ); # set author object
189 $book->author_id(); # get the plain id
190
191 # To retrieve the plain id if you used the ugly version:
192 $book->get_column('author_id');
2535b501 193
503536d5 194
13523f29 195If the relationship is optional -- i.e. the column containing the
196foreign key can be NULL -- then the belongs_to relationship does the
197right thing. Thus, in the example above C<< $obj->author >> would
198return C<undef>. However in this case you would probably want to set
199the L<join_type|DBIx::Class::Relationship/join_type> attribute so that
200a C<LEFT JOIN> is done, which makes complex resultsets involving
201C<join> or C<prefetch> operations work correctly. The modified
202declaration is shown below:
2c3ad870 203
b8810cc5 204 # in a Book class (where Author has_many Books)
951ab5ab 205 __PACKAGE__->belongs_to(
8273e845 206 author =>
951ab5ab 207 'My::DBIC::Schema::Author',
8273e845 208 'author',
951ab5ab 209 { join_type => 'left' }
210 );
2c3ad870 211
212
b8810cc5 213Cascading deletes are off by default on a C<belongs_to>
214relationship. To turn them on, pass C<< cascade_delete => 1 >>
215in the $attr hashref.
e8e9e5c7 216
cef1bdda 217By default, DBIC will return undef and avoid querying the database if a
218C<belongs_to> accessor is called when any part of the foreign key IS NULL. To
13523f29 219disable this behavior, pass C<< undef_on_null_fk => 0 >> in the C<\%attrs>
cef1bdda 220hashref.
c89815db 221
8091aa91 222NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent
223of C<has_a>.
503536d5 224
13523f29 225See L<DBIx::Class::Relationship::Base/attributes> for documentation on relationship
684af876 226methods and valid relationship attributes. Also see L<DBIx::Class::ResultSet>
227for a L<list of standard resultset attributes|DBIx::Class::ResultSet/ATTRIBUTES>
228which can be assigned to relationships as well.
2535b501 229
bfab575a 230=head2 has_many
503536d5 231
2f3105ce 232=over 4
233
fb13a49f 234=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
2f3105ce 235
236=back
237
1c4819f0 238Creates a one-to-many relationship where the foreign class refers to
239this class's primary key. This relationship refers to zero or more
8273e845 240records in the foreign table (e.g. a C<LEFT JOIN>). This relationship
1c4819f0 241defaults to using the end of this classes namespace as the foreign key
242in C<$related_class> to resolve the join, unless C<$their_fk_column>
243specifies the foreign key column in C<$related_class> or C<cond>
13523f29 244specifies a reference to a join condition.
7a2c1380 245
246=over
247
248=item accessor_name
249
250This argument is the name of the method you can call on a
fb13a49f 251L<Result|DBIx::Class::Manual::ResultClass> object to retrieve a resultset of the related
252class restricted to the ones related to the result object. In list
253context it returns the result objects. This is often called the
951ab5ab 254C<relation(ship) name>.
7a2c1380 255
951ab5ab 256Use this accessor_name in L<DBIx::Class::ResultSet/join>
7a2c1380 257or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
258indicated by this relationship.
259
260=item related_class
261
262This is the class name of the table which contains a foreign key
263column containing PK values of this class.
264
b0acf5d8 265=item their_fk_column
7a2c1380 266
267The column name on the related class that contains the foreign key.
268
269OR
270
271=item cond
272
13523f29 273A hashref, arrayref or coderef specifying a custom join expression. For
6c30f9c3 274more info see L<DBIx::Class::Relationship::Base/condition>.
da2e2b76 275
7a2c1380 276=back
277
b8810cc5 278 # in an Author class (where Author has_many Books)
e951858e 279 # assuming related class is storing our PK in "author_id"
951ab5ab 280 My::DBIC::Schema::Author->has_many(
8273e845 281 books =>
282 'My::DBIC::Schema::Book',
951ab5ab 283 'author_id'
284 );
285
e951858e 286 # OR (same result)
951ab5ab 287 My::DBIC::Schema::Author->has_many(
8273e845 288 books =>
289 'My::DBIC::Schema::Book',
e951858e 290 { 'foreign.author_id' => 'self.id' },
951ab5ab 291 );
d4daee7b 292
e951858e 293 # OR (similar result, assuming related_class is storing our PK, in "author")
294 # (the "author" is guessed at from "Author" in the class namespace)
951ab5ab 295 My::DBIC::Schema::Author->has_many(
8273e845 296 books =>
297 'My::DBIC::Schema::Book',
951ab5ab 298 );
e951858e 299
2535b501 300
951ab5ab 301 # Usage
8273e845 302 # resultset of Books belonging to author
951ab5ab 303 my $booklist = $author->books;
304
305 # resultset of Books belonging to author, restricted by author name
306 my $booklist = $author->books({
bc0c9800 307 name => { LIKE => '%macaroni%' },
308 { prefetch => [qw/book/],
309 });
503536d5 310
951ab5ab 311 # array of Book objects belonging to author
312 my @book_objs = $author->books;
503536d5 313
951ab5ab 314 # force resultset even in list context
315 my $books_rs = $author->books;
316 ( $books_rs ) = $obj->books_rs;
317
318 # create a new book for this author, the relation fields are auto-filled
319 $author->create_related('books', \%col_data);
320 # alternative method for the above
321 $author->add_to_books(\%col_data);
2535b501 322
2535b501 323
13523f29 324Three methods are created when you create a has_many relationship.
325The first method is the expected accessor method, C<$accessor_name()>.
326The second is almost exactly the same as the accessor method but "_rs"
327is added to the end of the method name, eg C<$accessor_name_rs()>.
328This method works just like the normal accessor, except that it always
329returns a resultset, even in list context. The third method, named C<<
330add_to_$relname >>, will also be added to your Row items; this allows
331you to insert new related items, using the same mechanism as in
5b89a768 332L<DBIx::Class::Relationship::Base/"create_related">.
d2113a68 333
8091aa91 334If you delete an object in a class with a C<has_many> relationship, all
b8810cc5 335the related objects will be deleted as well. To turn this behaviour off,
2a2ab6ab 336pass C<< cascade_delete => 0 >> in the C<$attr> hashref.
337
338The cascaded operations are performed after the requested delete or
339update, so if your database has a constraint on the relationship, it
340will have deleted/updated the related records or raised an exception
341before DBIx::Class gets to perform the cascaded operation.
503536d5 342
f4e92c39 343If you copy an object in a class with a C<has_many> relationship, all
344the related objects will be copied as well. To turn this behaviour off,
2fef093d 345pass C<< cascade_copy => 0 >> in the C<$attr> hashref. The behaviour
346defaults to C<< cascade_copy => 1 >>.
f4e92c39 347
13523f29 348See L<DBIx::Class::Relationship::Base/attributes> for documentation on
349relationship methods and valid relationship attributes. Also see
350L<DBIx::Class::ResultSet> for a L<list of standard resultset
351attributes|DBIx::Class::ResultSet/ATTRIBUTES> which can be assigned to
352relationships as well.
2535b501 353
bfab575a 354=head2 might_have
503536d5 355
2f3105ce 356=over 4
357
fb13a49f 358=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
2f3105ce 359
360=back
361
7a2c1380 362Creates an optional one-to-one relationship with a class. This relationship
363defaults to using C<$accessor_name> as the foreign key in C<$related_class> to
b0acf5d8 364resolve the join, unless C<$their_fk_column> specifies the foreign key
951ab5ab 365column in C<$related_class> or C<cond> specifies a reference to a join
13523f29 366condition.
7a2c1380 367
368=over
369
370=item accessor_name
371
372This argument is the name of the method you can call on a
fb13a49f 373L<Result|DBIx::Class::Manual::ResultClass> object to retrieve the instance of the foreign
951ab5ab 374class matching this relationship. This is often called the
375C<relation(ship) name>.
7a2c1380 376
951ab5ab 377Use this accessor_name in L<DBIx::Class::ResultSet/join>
7a2c1380 378or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
379indicated by this relationship.
380
381=item related_class
382
383This is the class name of the table which contains a foreign key
384column containing PK values of this class.
385
b0acf5d8 386=item their_fk_column
7a2c1380 387
388The column name on the related class that contains the foreign key.
389
390OR
391
392=item cond
393
13523f29 394A hashref, arrayref or coderef specifying a custom join expression. For
6c30f9c3 395more info see L<DBIx::Class::Relationship::Base/condition>.
7a2c1380 396
397=back
398
951ab5ab 399 # Author may have an entry in the pseudonym table
400 My::DBIC::Schema::Author->might_have(
401 pseudonym =>
402 'My::DBIC::Schema::Pseudonym',
403 'author_id',
404 );
405
406 # OR (same result, assuming the related_class stores our PK)
407 My::DBIC::Schema::Author->might_have(
408 pseudonym =>
409 'My::DBIC::Schema::Pseudonym',
410 );
411
412 # OR (same result)
413 My::DBIC::Schema::Author->might_have(
414 pseudonym =>
415 'My::DBIC::Schema::Pseudonym',
416 { 'foreign.author_id' => 'self.id' },
417 );
418
419 # Usage
420 my $pname = $author->pseudonym; # to get the Pseudonym object
9e64dfbf 421
c99393ff 422If you update or delete an object in a class with a C<might_have>
b8810cc5 423relationship, the related object will be updated or deleted as well. To
424turn off this behavior, add C<< cascade_delete => 0 >> to the C<$attr>
2a2ab6ab 425hashref.
426
427The cascaded operations are performed after the requested delete or
428update, so if your database has a constraint on the relationship, it
429will have deleted/updated the related records or raised an exception
430before DBIx::Class gets to perform the cascaded operation.
503536d5 431
13523f29 432See L<DBIx::Class::Relationship::Base/attributes> for documentation on
433relationship methods and valid relationship attributes. Also see
434L<DBIx::Class::ResultSet> for a L<list of standard resultset
435attributes|DBIx::Class::ResultSet/ATTRIBUTES> which can be assigned to
436relationships as well.
2f3105ce 437
13523f29 438Note that if you supply a condition on which to join, and the column in the
dc571b76 439current table allows nulls (i.e., has the C<is_nullable> attribute set to a
440true value), than C<might_have> will warn about this because it's naughty and
13523f29 441you shouldn't do that. The warning will look something like:
dc571b76 442
6c4f4d69 443 "might_have/has_one" must not be on columns with is_nullable set to true (MySchema::SomeClass/key)
dc571b76 444
445If you must be naughty, you can suppress the warning by setting
446C<DBIC_DONT_VALIDATE_RELS> environment variable to a true value. Otherwise,
13523f29 447you probably just meant to use C<DBIx::Class::Relationship/belongs_to>.
dc571b76 448
bfab575a 449=head2 has_one
450
2f3105ce 451=over 4
452
fb13a49f 453=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
2f3105ce 454
455=back
456
951ab5ab 457Creates a one-to-one relationship with a class. This relationship
458defaults to using C<$accessor_name> as the foreign key in C<$related_class> to
b0acf5d8 459resolve the join, unless C<$their_fk_column> specifies the foreign key
951ab5ab 460column in C<$related_class> or C<cond> specifies a reference to a join
13523f29 461condition.
2f3105ce 462
951ab5ab 463=over
464
465=item accessor_name
466
467This argument is the name of the method you can call on a
fb13a49f 468L<Result|DBIx::Class::Manual::ResultClass> object to retrieve the instance of the foreign
951ab5ab 469class matching this relationship. This is often called the
470C<relation(ship) name>.
471
472Use this accessor_name in L<DBIx::Class::ResultSet/join>
473or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
474indicated by this relationship.
475
476=item related_class
477
478This is the class name of the table which contains a foreign key
479column containing PK values of this class.
480
b0acf5d8 481=item their_fk_column
951ab5ab 482
483The column name on the related class that contains the foreign key.
484
485OR
486
487=item cond
488
13523f29 489A hashref, arrayref or coderef specifying a custom join expression. For
6c30f9c3 490more info see L<DBIx::Class::Relationship::Base/condition>.
951ab5ab 491
492=back
bfab575a 493
951ab5ab 494 # Every book has exactly one ISBN
495 My::DBIC::Schema::Book->has_one(
8273e845 496 isbn =>
951ab5ab 497 'My::DBIC::Schema::ISBN',
498 'book_id',
499 );
500
501 # OR (same result, assuming related_class stores our PK)
502 My::DBIC::Schema::Book->has_one(
8273e845 503 isbn =>
951ab5ab 504 'My::DBIC::Schema::ISBN',
505 );
506
507 # OR (same result)
508 My::DBIC::Schema::Book->has_one(
8273e845 509 isbn =>
951ab5ab 510 'My::DBIC::Schema::ISBN',
511 { 'foreign.book_id' => 'self.id' },
512 );
513
514 # Usage
515 my $isbn_obj = $book->isbn; # to get the ISBN object
516
517Creates a one-to-one relationship with another class. This is just
518like C<might_have>, except the implication is that the other object is
519always present. The only difference between C<has_one> and
520C<might_have> is that C<has_one> uses an (ordinary) inner join,
521whereas C<might_have> defaults to a left join.
503536d5 522
13523f29 523The has_one relationship should be used when a row in the table must
524have exactly one related row in another table. If the related row
525might not exist in the foreign table, use the
526L<DBIx::Class::Relationship/might_have> relationship.
2f3105ce 527
528In the above example, each Book in the database is associated with exactly one
529ISBN object.
7411204b 530
13523f29 531See L<DBIx::Class::Relationship::Base/attributes> for documentation on
532relationship methods and valid relationship attributes. Also see
533L<DBIx::Class::ResultSet> for a L<list of standard resultset
534attributes|DBIx::Class::ResultSet/ATTRIBUTES> which can be assigned to
535relationships as well.
87c4e602 536
dc571b76 537Note that if you supply a condition on which to join, if the column in the
538current table allows nulls (i.e., has the C<is_nullable> attribute set to a
539true value), than warnings might apply just as with
540L<DBIx::Class::Relationship/might_have>.
541
2535b501 542=head2 many_to_many
2f3105ce 543
544=over 4
545
fb13a49f 546=item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
303cf522 547
2f3105ce 548=back
549
7cf4ae7a 550C<many_to_many> is a I<Relationship bridge> which has a specific
551meaning in DBIx::Class, see the definition in the
552L<Glossary|DBIx::Class::Manual::Glossary/Relationship bridge>.
553
7a2c1380 554C<many_to_many> is not strictly a relationship in its own right. Instead, it is
555a bridge between two resultsets which provide the same kind of convenience
8273e845 556accessors as true relationships provide. Although the accessor will return a
557resultset or collection of objects just like has_many does, you cannot call
7a2c1380 558C<related_resultset> and similar methods which operate on true relationships.
559
560=over
561
562=item accessor_name
563
564This argument is the name of the method you can call on a
fb13a49f 565L<Result|DBIx::Class::Manual::ResultClass> object to retrieve the rows matching this
7a2c1380 566relationship.
567
568On a many_to_many, unlike other relationships, this cannot be used in
569L<DBIx::Class::ResultSet/search> to join tables. Use the relations
570bridged across instead.
571
572=item link_rel_name
573
574This is the accessor_name from the has_many relationship we are
575bridging from.
576
577=item foreign_rel_name
578
579This is the accessor_name of the belongs_to relationship in the link
580table that we are bridging across (which gives us the table we are
581bridging to).
582
583=back
584
2f3105ce 585To create a many_to_many relationship from Actor to Role:
586
75d07914 587 My::DBIC::Schema::Actor->has_many( actor_roles =>
d2113a68 588 'My::DBIC::Schema::ActorRoles',
589 'actor' );
75d07914 590 My::DBIC::Schema::ActorRoles->belongs_to( role =>
d2113a68 591 'My::DBIC::Schema::Role' );
75d07914 592 My::DBIC::Schema::ActorRoles->belongs_to( actor =>
d2113a68 593 'My::DBIC::Schema::Actor' );
594
595 My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles',
71d5ed18 596 'role' );
bc0c9800 597
2f3105ce 598And, for the reverse relationship, from Role to Actor:
599
600 My::DBIC::Schema::Role->has_many( actor_roles =>
601 'My::DBIC::Schema::ActorRoles',
602 'role' );
603
604 My::DBIC::Schema::Role->many_to_many( actors => 'actor_roles', 'actor' );
605
787d6a29 606To add a role for your actor, and fill in the year of the role in the
607actor_roles table:
608
609 $actor->add_to_roles($role, { year => 1995 });
610
2535b501 611In the above example, ActorRoles is the link table class, and Role is the
612foreign class. The C<$link_rel_name> parameter is the name of the accessor for
613the has_many relationship from this table to the link table, and the
614C<$foreign_rel_name> parameter is the accessor for the belongs_to relationship
615from the link table to the foreign table.
616
d2113a68 617To use many_to_many, existing relationships from the original table to the link
75d07914 618table, and from the link table to the end table must already exist, these
d2113a68 619relation names are then used in the many_to_many call.
7411204b 620
2535b501 621In the above example, the Actor class will have 3 many_to_many accessor methods
951ab5ab 622set: C<roles>, C<add_to_roles>, C<set_roles>, and similarly named accessors
2535b501 623will be created for the Role class for the C<actors> many_to_many
624relationship.
625
13523f29 626See L<DBIx::Class::Relationship::Base/attributes> for documentation on
627relationship methods and valid relationship attributes. Also see
628L<DBIx::Class::ResultSet> for a L<list of standard resultset
629attributes|DBIx::Class::ResultSet/ATTRIBUTES> which can be assigned to
630relationships as well.
2f3105ce 631
34d52be2 632=cut
633
b8e1e21f 6341;
34d52be2 635
0c11ad0e 636=head1 AUTHOR AND CONTRIBUTORS
34d52be2 637
0c11ad0e 638See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
34d52be2 639
640=head1 LICENSE
641
642You may distribute this code under the same terms as Perl itself.
643
644=cut
645