lib/DBIx/Class/Relationship.pm

   1 package DBIx::Class::Relationship;
   2
   3 use strict;
   4 use warnings;
   5
   6 use base qw/DBIx::Class/;
   7
   8 __PACKAGE__->load_own_components(qw/
   9   Helpers
  10   Accessor
  11   CascadeActions
  12   ProxyMethods
  13   Base
  14 /);
  15
  16 =head1 NAME
  17
  18 DBIx::Class::Relationship - Inter-table relationships
  19
  20 =head1 SYNOPSIS
  21
  22   MyDB::Schema::Actor->has_many('actorroles' => 'MyDB::Schema::ActorRole',
  23                                 'actor');
  24   MyDB::Schema::Role->has_many('actorroles' => 'MyDB::Schema::ActorRole',
  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' });
  34   $schema->resultset('ActorRole')->add_to_roles({ Name => 'Sherlock Holmes'});
  35
  36 See L<DBIx::Class::Manual::Cookbook> for more.
  37
  38 =head1 DESCRIPTION
  39
  40 This class provides methods to set up relationships between the tables
  41 in your database model. Relationships are the most useful and powerful
  42 technique that L<DBIx::Class> provides. To create efficient database queries,
  43 create relationships between any and all tables that have something in
  44 common, for example if you have a table Authors:
  45
  46   ID  | Name | Age
  47  ------------------
  48    1  | Fred | 30
  49    2  | Joe  | 32
  50
  51 and a table Books:
  52
  53   ID  | Author | Name
  54  --------------------
  55    1  |      1 | Rulers of the universe
  56    2  |      1 | Rulers of the galaxy
  57
  58 Then without relationships, the method of getting all books by Fred goes like
  59 this:
  60
  61  my $fred = $schema->resultset('Author')->find({ Name => 'Fred' });
  62  my $fredsbooks = $schema->resultset('Book')->search({ Author => $fred->ID });
  63 With a has_many relationship called "books" on Author (see below for details),
  64 we can do this instead:
  65
  66  my $fredsbooks = $schema->resultset('Author')->find({ Name => 'Fred' })->books;
  67
  68 Each relationship sets up an accessor method on the
  69 L<DBIx::Class::Manual::Glossary/"Row"> objects that represent the items
  70 of your table. From L<DBIx::Class::Manual::Glossary/"ResultSet"> objects,
  71 the relationships can be searched using the "search_related" method.
  72 In list context, each returns a list of Row objects for the related class,
  73 in scalar context, a new ResultSet representing the joined tables is
  74 returned. Thus, the calls can be chained to produce complex queries.
  75 Since the database is not actually queried until you attempt to retrieve
  76 the data for an actual item, no time is wasted producing them.
  77
  78  my $cheapfredbooks = $schema->resultset('Author')->find({
  79    Name => 'Fred',
  80  })->books->search_related('prices', {
  81    Price => { '<=' => '5.00' },
  82  });
  83
  84 will produce a query something like:
  85
  86  SELECT * FROM Author me
  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
  91 all without needing multiple fetches.
  92
  93 Only the helper methods for setting up standard relationship types
  94 are documented here. For the basic, lower-level methods, and a description
  95 of all the useful *_related methods that you get for free, see
  96 L<DBIx::Class::Relationship::Base>.
  97
  98 =head1 METHODS
  99
 100 All helper methods take the following arguments:
 101
 102   __PACKAGE__>$method_name('relname', 'Foreign::Class', $cond, $attrs);
 103
 104 Both C<$cond> and C<$attrs> are optional. Pass C<undef> for C<$cond> if
 105 you want to use the default value for it, but still want to set C<$attrs>.
 106
 107 See L<DBIx::Class::Relationship::Base> for a list of valid attributes and valid
 108 relationship attributes.
 109
 110 =head2 belongs_to
 111
 112 =over 4
 113
 114 =item Arguments: $accessor_name, $related_class, $foreign_key_column|$cond?, $attr?
 115
 116 =back
 117
 118 Creates a relationship where the calling class stores the foreign class's
 119 primary key in one (or more) of its columns. This relationship defaults to
 120 using C<$accessor_name> as the foreign key in C<$related_class> to resolve the
 121 join, unless C<$foreign_key_column> specifies the foreign key column in
 122 C<$related_class> or C<$cond> specifies a reference to a join condition hash.
 123
 124 =over
 125
 126 =item accessor_name
 127
 128 This argument is the name of the method you can call on a
 129 L<DBIx::Class::Row> object to retrieve the instance of the foreign
 130 class matching this relationship.
 131
 132 Use this accessor_name (relation name) in L<DBIx::Class::ResultSet/join>
 133 or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
 134 indicated by this relationship.
 135
 136 =item related_class
 137
 138 This is the class name of the table referenced by the foreign key in
 139 this class.
 140
 141 =item foreign_key_column
 142
 143 The column name on this class that contains the foreign key.
 144
 145 OR
 146
 147 =item cond
 148
 149 A hashref where the keys are C<foreign.$column_on_related_table> and
 150 the values are C<self.$foreign_key_column>. This is useful for
 151 relations that are across multiple columns.
 152
 153 =back
 154
 155
 156   # in a Book class (where Author has many Books)
 157   My::DBIC::Schema::Book->belongs_to( author => 'My::DBIC::Schema::Author' );
 158
 159   my $author_obj = $obj->author; # get author object
 160   $obj->author( $new_author_obj ); # set author object
 161
 162 The above belongs_to relationship could also have been specified as,
 163
 164   My::DBIC::Schema::Book->belongs_to( author,
 165                                       'My::DBIC::Schema::Author',
 166                                       { 'foreign.author' => 'self.author' } );
 167
 168 If the relationship is optional -- i.e. the column containing the foreign key
 169 can be NULL -- then the belongs_to relationship does the right thing. Thus, in
 170 the example above C<$obj-E<gt>author> would return C<undef>.  However in this
 171 case you would probably want to set the C<join_type> attribute so that a C<LEFT
 172 JOIN> is done, which makes complex resultsets involving C<join> or C<prefetch>
 173 operations work correctly.  The modified declaration is shown below:
 174
 175   # in a Book class (where Author has_many Books)
 176   __PACKAGE__->belongs_to(author => 'My::DBIC::Schema::Author',
 177                           'author', {join_type => 'left'});
 178
 179
 180 Cascading deletes are off by default on a C<belongs_to>
 181 relationship. To turn them on, pass C<< cascade_delete => 1 >>
 182 in the $attr hashref.
 183
 184 NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent
 185 of C<has_a>.
 186
 187 See L<DBIx::Class::Relationship::Base> for documentation on relationship
 188 methods and valid relationship attributes.
 189
 190 =head2 has_many
 191
 192 =over 4
 193
 194 =item Arguments: $accessor_name, $related_class, $foreign_key_column|$cond?, $attr?
 195
 196 =back
 197
 198 Creates a one-to-many relationship, where the corresponding elements of the
 199 foreign class store the calling class's primary key in one (or more) of its
 200 columns. This relationship defaults to using C<$accessor_name> as the foreign
 201 key in C<$related_class> to resolve the join, unless C<$foreign_key_column>
 202 specifies the foreign key column in C<$related_class> or C<$cond> specifies a
 203 reference to a join condition hash.
 204
 205 =over
 206
 207 =item accessor_name
 208
 209 This argument is the name of the method you can call on a
 210 L<DBIx::Class::Row> object to retrieve a resultset of the related
 211 class restricted to the ones related to the row object. In list
 212 context it returns the row objects.
 213
 214 Use this accessor_name (relation name) in L<DBIx::Class::ResultSet/join>
 215 or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
 216 indicated by this relationship.
 217
 218 =item related_class
 219
 220 This is the class name of the table which contains a foreign key
 221 column containing PK values of this class.
 222
 223 =item foreign_key_column
 224
 225 The column name on the related class that contains the foreign key.
 226
 227 OR
 228
 229 =item cond
 230
 231 A hashref where the keys are C<foreign.$column_on_related_table> and
 232 the values are C<self.$foreign_key_column>. This is useful for
 233 relations that are across multiple columns.
 234
 235 =back
 236
 237   # in an Author class (where Author has_many Books)
 238   My::DBIC::Schema::Author->has_many(books => 'My::DBIC::Schema::Book', 'author');
 239
 240   my $booklist = $obj->books;
 241   my $booklist = $obj->books({
 242     name => { LIKE => '%macaroni%' },
 243     { prefetch => [qw/book/],
 244   });
 245   my @book_objs = $obj->books;
 246   my $books_rs = $obj->books;
 247   ( $books_rs ) = $obj->books_rs;
 248
 249   $obj->add_to_books(\%col_data);
 250
 251 The above C<has_many> relationship could also have been specified with an
 252 explicit join condition:
 253
 254   My::DBIC::Schema::Author->has_many( books => 'My::DBIC::Schema::Book', {
 255     'foreign.author' => 'self.author',
 256   });
 257
 258 Three methods are created when you create a has_many relationship.  The first
 259 method is the expected accessor method, C<$accessor_name()>.  The second is
 260 almost exactly the same as the accessor method but "_rs" is added to the end of
 261 the method name.  This method works just like the normal accessor, except that
 262 it returns a resultset no matter what, even in list context. The third method,
 263 named C<< add_to_$relname >>, will also be added to your Row items; this
 264 allows you to insert new related items, using the same mechanism as in
 265 L<DBIx::Class::Relationship::Base/"create_related">.
 266
 267 If you delete an object in a class with a C<has_many> relationship, all
 268 the related objects will be deleted as well.  To turn this behaviour off,
 269 pass C<< cascade_delete => 0 >> in the C<$attr> hashref. However, any
 270 database-level cascade or restrict will take precedence over a
 271 DBIx-Class-based cascading delete.
 272
 273 See L<DBIx::Class::Relationship::Base> for documentation on relationship
 274 methods and valid relationship attributes.
 275
 276 =head2 might_have
 277
 278 =over 4
 279
 280 =item Arguments: $accessor_name, $related_class, $foreign_key_column|$cond?, $attr?
 281
 282 =back
 283
 284 Creates an optional one-to-one relationship with a class. This relationship
 285 defaults to using C<$accessor_name> as the foreign key in C<$related_class> to
 286 resolve the join, unless C<$foreign_key_column> specifies the foreign key
 287 column in C<$related_class> or C<$cond> specifies a reference to a join
 288 condition hash.
 289
 290 =over
 291
 292 =item accessor_name
 293
 294 This argument is the name of the method you can call on a
 295 L<DBIx::Class::Row> object to retrieve the instance of the foreign
 296 class matching this relationship.
 297
 298 Use this accessor_name (relation name) in L<DBIx::Class::ResultSet/join>
 299 or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
 300 indicated by this relationship.
 301
 302 =item related_class
 303
 304 This is the class name of the table which contains a foreign key
 305 column containing PK values of this class.
 306
 307 =item foreign_key_column
 308
 309 The column name on the related class that contains the foreign key.
 310
 311 OR
 312
 313 =item cond
 314
 315 A hashref where the keys are C<foreign.$column_on_related_table> and
 316 the values are C<self.$foreign_key_column>. This is useful for
 317 relations that are across multiple columns.
 318
 319 =back
 320
 321   My::DBIC::Schema::Author->might_have( pseudonym =>
 322                                         'My::DBIC::Schema::Pseudonym' );
 323
 324   my $pname = $obj->pseudonym; # to get the Pseudonym object
 325
 326 The above might_have relationship could have been specified as:
 327
 328   My::DBIC::Schema::Author->might_have( pseudonym =>
 329                                         'My::DBIC::Schema::Pseudonym',
 330                                         'author' );
 331
 332 Or even:
 333
 334   My::DBIC::Schema::Author->might_have( pseudonym =>
 335                                         'My::DBIC::Schema::Pseudonym',
 336                                         { 'foreign.author' => 'self.author' } );
 337
 338 If you update or delete an object in a class with a C<might_have>
 339 relationship, the related object will be updated or deleted as well. To
 340 turn off this behavior, add C<< cascade_delete => 0 >> to the C<$attr>
 341 hashref. Any database-level update or delete constraints will override
 342 this behavior.
 343
 344 See L<DBIx::Class::Relationship::Base> for documentation on relationship
 345 methods and valid relationship attributes.
 346
 347 =head2 has_one
 348
 349 =over 4
 350
 351 =item Arguments: $accessor_name, $related_class_name, $join_condition?, $attr?
 352
 353 =back
 354
 355   My::DBIC::Schema::Book->has_one(isbn => 'My::DBIC::Schema::ISBN');
 356
 357   my $isbn_obj = $obj->isbn; # to get the ISBN object
 358
 359 Creates a one-to-one relationship with another class. This is just like
 360 C<might_have>, except the implication is that the other object is always
 361 present. The only difference between C<has_one> and C<might_have> is that
 362 C<has_one> uses an (ordinary) inner join, whereas C<might_have> uses a
 363 left join.
 364
 365 The has_one relationship should be used when a row in the table has exactly one
 366 related row in another table. If the related row might not exist in the foreign
 367 table, use the L<DBIx::Class::Relationship/might_have> relationship.
 368
 369 In the above example, each Book in the database is associated with exactly one
 370 ISBN object.
 371
 372 See L<DBIx::Class::Relationship::Base> for documentation on relationship
 373 methods and valid relationship attributes.
 374
 375 =head2 many_to_many
 376
 377 =over 4
 378
 379 =item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name, $attr?
 380
 381 =back
 382
 383 C<many_to_many> is not strictly a relationship in its own right. Instead, it is
 384 a bridge between two resultsets which provide the same kind of convenience
 385 accessors as true relationships provide. Although the accessor will return a
 386 resultset or collection of objects just like has_many does, you cannot call
 387 C<related_resultset> and similar methods which operate on true relationships.
 388
 389 =over
 390
 391 =item accessor_name
 392
 393 This argument is the name of the method you can call on a
 394 L<DBIx::Class::Row> object to retrieve the rows matching this
 395 relationship.
 396
 397 On a many_to_many, unlike other relationships, this cannot be used in
 398 L<DBIx::Class::ResultSet/search> to join tables. Use the relations
 399 bridged across instead.
 400
 401 =item link_rel_name
 402
 403 This is the accessor_name from the has_many relationship we are
 404 bridging from.
 405
 406 =item foreign_rel_name
 407
 408 This is the accessor_name of the belongs_to relationship in the link
 409 table that we are bridging across (which gives us the table we are
 410 bridging to).
 411
 412 =back
 413
 414 To create a many_to_many relationship from Actor to Role:
 415
 416   My::DBIC::Schema::Actor->has_many( actor_roles =>
 417                                      'My::DBIC::Schema::ActorRoles',
 418                                      'actor' );
 419   My::DBIC::Schema::ActorRoles->belongs_to( role =>
 420                                             'My::DBIC::Schema::Role' );
 421   My::DBIC::Schema::ActorRoles->belongs_to( actor =>
 422                                             'My::DBIC::Schema::Actor' );
 423
 424   My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles',
 425                                          'role' );
 426
 427 And, for the reverse relationship, from Role to Actor:
 428
 429   My::DBIC::Schema::Role->has_many( actor_roles =>
 430                                     'My::DBIC::Schema::ActorRoles',
 431                                     'role' );
 432
 433   My::DBIC::Schema::Role->many_to_many( actors => 'actor_roles', 'actor' );
 434
 435 To add a role for your actor, and fill in the year of the role in the
 436 actor_roles table:
 437
 438   $actor->add_to_roles($role, { year => 1995 });
 439
 440 In the above example, ActorRoles is the link table class, and Role is the
 441 foreign class. The C<$link_rel_name> parameter is the name of the accessor for
 442 the has_many relationship from this table to the link table, and the
 443 C<$foreign_rel_name> parameter is the accessor for the belongs_to relationship
 444 from the link table to the foreign table.
 445
 446 To use many_to_many, existing relationships from the original table to the link
 447 table, and from the link table to the end table must already exist, these
 448 relation names are then used in the many_to_many call.
 449
 450 In the above example, the Actor class will have 3 many_to_many accessor methods
 451 set: C<$roles>, C<$add_to_roles>, C<$set_roles>, and similarly named accessors
 452 will be created for the Role class for the C<actors> many_to_many
 453 relationship.
 454
 455 See L<DBIx::Class::Relationship::Base> for documentation on relationship
 456 methods and valid relationship attributes.
 457
 458 =cut
 459
 460 1;
 461
 462 =head1 AUTHORS
 463
 464 Matt S. Trout <mst@shadowcatsystems.co.uk>
 465
 466 =head1 LICENSE
 467
 468 You may distribute this code under the same terms as Perl itself.
 469
 470 =cut
 471