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 See L<DBIx::Class::Relationship::Base> for a list of valid attributes.
 107
 108 =head2 belongs_to
 109
 110 =over 4
 111
 112 =item Arguments: $accessor_name, $related_class, $foreign_key_column?, $attr?
 113
 114 =back
 115
 116   # in a Book class (where Author has many Books)
 117   My::DBIC::Schema::Book->belongs_to(author => 'My::DBIC::Schema::Author');
 118   my $author_obj = $obj->author;
 119   $obj->author($new_author_obj);
 120
 121 Creates a relationship where the calling class stores the foreign class's
 122 primary key in one (or more) of its columns. If C<$cond> is a column name
 123 instead of a join condition hash, it is used as the name of the foreign key
 124 column in the calling class. If C<$cond> is not given, C<$accessor_name> is
 125 used as the column name.
 126
 127 If the relationship is optional -- i.e. the column containing the foreign key
 128 can be NULL -- then the belongs_to relationship does the right thing. Thus, in
 129 the example above C<$obj-E<gt>author> would return C<undef>.  However in this
 130 case you would probably want to set the C<join_type> attribute so that a C<LEFT
 131 JOIN> is done, which makes complex resultsets involving C<join> or C<prefetch>
 132 operations work correctly.  The modified declaration is shown below:
 133
 134   # in a Book class (where Author has_many Books)
 135   __PACKAGE__->belongs_to(author => 'My::DBIC::Schema::Author',
 136                           'author', {join_type => 'left'});
 137
 138
 139 Cascading deletes are off by default on a C<belongs_to>
 140 relationship. To turn them on, pass C<< cascade_delete => 1 >>
 141 in the $attr hashref.
 142
 143 NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent
 144 of C<has_a>.
 145
 146 =head2 has_many
 147
 148 =over 4
 149
 150 =item Arguments: $accessor_name, $related_class, $foreign_key_column?, $attr?
 151
 152 =back
 153
 154   # in an Author class (where Author has_many Books)
 155   My::DBIC::Schema::Author->has_many(books => 'My::DBIC::Schema::Book', 'author');
 156   my $booklist = $obj->books;
 157   my $booklist = $obj->books({
 158     name => { LIKE => '%macaroni%' },
 159     { prefetch => [qw/book/],
 160   });
 161   my @book_objs = $obj->books;
 162   my $books_rs = $obj->books;
 163   ( $books_rs ) = $obj->books_rs;
 164
 165   $obj->add_to_books(\%col_data);
 166
 167 Creates a one-to-many relationship, where the corresponding elements of the
 168 foreign class store the calling class's primary key in one (or more) of its
 169 columns. You should pass the name of the column in the foreign class as the
 170 C<$cond> argument, or specify a complete join condition.
 171
 172 Three methods are created when you create a has_many relationship.  The first
 173 method is the expected accessor method, C<$accessor_name()>.  The second is
 174 almost exactly the same as the accessor method but "_rs" is added to the end of
 175 the method name.  This method works just like the normal accessor, except that
 176 it returns a resultset no matter what, even in list context. The third method,
 177 named C<< add_to_<relname> >>, will also be added to your Row items; this
 178 allows you to insert new related items, using the same mechanism as in
 179 L<DBIx::Class::Relationship::Base/"create_related">.
 180
 181 If you delete an object in a class with a C<has_many> relationship, all
 182 the related objects will be deleted as well.  To turn this behaviour off,
 183 pass C<< cascade_delete => 0 >> in the C<$attr> hashref. However, any
 184 database-level cascade or restrict will take precedence over a
 185 DBIx-Class-based cascading delete.
 186
 187 =head2 might_have
 188
 189 =over 4
 190
 191 =item Arguments: $accessor_name, $related_class, $join_condition?, $attr?
 192
 193 =back
 194
 195   My::DBIC::Schema::Author->might_have(pseudonym =>
 196                                        'My::DBIC::Schema::Pseudonym');
 197
 198   my $pname = $obj->pseudonym; # to get the Pseudonym object
 199
 200 Creates an optional one-to-one relationship with a class. This relationship
 201 defaults to using the relationship name as the foreign key in C<$related_class>
 202 to resolve the join, unless C<$join_condition> specifies a column in
 203 C<$related_class> or a join condition hash reference.
 204
 205 If you update or delete an object in a class with a C<might_have>
 206 relationship, the related object will be updated or deleted as well. To
 207 turn off this behavior, add C<< cascade_delete => 0 >> to the C<$attr>
 208 hashref. Any database-level update or delete constraints will override
 209 this behavior.
 210
 211 In the above example
 212
 213 =head2 has_one
 214
 215 =over 4
 216
 217 =item Arguments: $accessor_name, $related_class_name, $join_condition?, $attr?
 218
 219 =back
 220
 221   My::DBIC::Schema::Book->has_one(isbn => 'My::DBIC::Schema::ISBN');
 222
 223   my $isbn_obj = $obj->isbn; # to get the ISBN object
 224
 225 Creates a one-to-one relationship with another class. This is just like
 226 C<might_have>, except the implication is that the other object is always
 227 present. The only difference between C<has_one> and C<might_have> is that
 228 C<has_one> uses an (ordinary) inner join, whereas C<might_have> uses a
 229 left join.
 230
 231 The has_one relationship should be used when a row in the table has exactly one
 232 related row in another table. If the related row might not exist in the foreign
 233 table, use the L<DBIx::Class::Relationship/might_have> relationship.
 234
 235 In the above example, each Book in the database is associated with exactly one
 236 ISBN object.
 237
 238 =head2 many_to_many
 239
 240 =over 4
 241
 242 =item Arguments:
 243
 244 =over 4
 245
 246 =item C<$accessor_name>: The name of the new many_to_many accessor,
 247
 248 =item C<$link_rel_name>: The accessor name of the has_many relationship from
 249                          the current table to the link table,
 250
 251 =item C<$foreign_rel_name>: The accessor name for the belongs_to relationship
 252                             from the link table to the foreign table
 253
 254 =item C<$attr>: A hash of relationship attributes for the created many_to_many
 255                 relationship accessors to use on the C<$foreign_rel_name>.
 256
 257 =back
 258
 259 =back
 260
 261 To create a many_to_many relationship from Actor to Role:
 262
 263   My::DBIC::Schema::Actor->has_many( actor_roles =>
 264                                      'My::DBIC::Schema::ActorRoles',
 265                                      'actor' );
 266   My::DBIC::Schema::ActorRoles->belongs_to( role =>
 267                                             'My::DBIC::Schema::Role' );
 268   My::DBIC::Schema::ActorRoles->belongs_to( actor =>
 269                                             'My::DBIC::Schema::Actor' );
 270
 271   My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles',
 272                                          'role' );
 273
 274 And, for the reverse relationship, from Role to Actor:
 275
 276   My::DBIC::Schema::Role->has_many( actor_roles =>
 277                                     'My::DBIC::Schema::ActorRoles',
 278                                     'role' );
 279
 280   My::DBIC::Schema::Role->many_to_many( actors => 'actor_roles', 'actor' );
 281
 282 Creates accessors bridging two relationships; not strictly a relationship in
 283 its own right, although the accessor will return a resultset or collection of
 284 objects just as a has_many would.
 285
 286 To use many_to_many, existing relationships from the original table to the link
 287 table, and from the link table to the end table must already exist, these
 288 relation names are then used in the many_to_many call.
 289
 290 In the above example, the Role class will have 3 many_to_many accessor methods
 291 set: C<$roles>, C<$add_to_roles>, C<$set_roles>, and similarly named accessors
 292 will be created for the Actor class. See L<DBIx::Class::Relationship::Base> for
 293 more information.
 294
 295 =cut
 296
 297 1;
 298
 299 =head1 AUTHORS
 300
 301 Matt S. Trout <mst@shadowcatsystems.co.uk>
 302
 303 =head1 LICENSE
 304
 305 You may distribute this code under the same terms as Perl itself.
 306
 307 =cut
 308