DBIx::Class::Relationship::Base(3p)

NAME
DBIx::Class::Relationship::Base - Inter-table relationships

SYNOPSIS

DESCRIPTION
This class provides methods to describe the relationships between the tables in your database model. These are the "bare bones" relationships methods, for predefined ones, look in DBIx::Class::Relationship.

METHODS

  add_relationship

Arguments: 'relname', 'Foreign::Class', $cond, $attrs

  __PACKAGE__->add_relationship('relname', 'Foreign::Class', $cond, $attrs);

The condition needs to be an SQL::Abstract-style representation of the join between the tables. When resolving the condition for use in a "JOIN", keys using the pseudo-table "foreign" are resolved to mean "the Table on the other side of the relationship", and values using the pseudo-table "self" are resolved to mean "the Table this class is representing". Other restrictions, such as by value, sub-select and other tables, may also be used. Please check your database for "JOIN" parameter support.

For example, if you're creating a relationship from "Author" to "Book", where the "Book" table has a column "author_id" containing the ID of the "Author" row:

  { 'foreign.author_id' => 'self.id' }

will result in the "JOIN" clause

  author me JOIN book book ON book.author_id = me.id

For multi-column foreign keys, you will need to specify a "foreign"-to-"self" mapping for each column in the key. For example, if you're creating a relationship from "Book" to "Edition", where the "Edition" table refers to a publisher and a type (e.g. "paperback"):

  {
    'foreign.publisher_id' => 'self.publisher_id',
    'foreign.type_id'      => 'self.type_id',
  }

This will result in the "JOIN" clause:

  book me JOIN edition edition ON edition.publisher_id = me.publisher_id
    AND edition.type_id = me.type_id

Each key-value pair provided in a hashref will be used as "AND"ed conditions. To add an "OR"ed condition, use an arrayref of hashrefs. See the SQL::Abstract documentation for more details.

In addition to standard result set attributes, the following attributes are also valid:

join_type
    Explicitly specifies the type of join to use in the relationship. Any SQL join type is valid, e.g. "LEFT" or "RIGHT". It will be placed in the SQL command immediately before "JOIN".

proxy
    An arrayref containing a list of accessors in the foreign class to create in the main class. If, for example, you do the following:

      MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes',
        undef, {
          proxy => [ qw/notes/ ],
        });

    Then, assuming MyDB::Schema::LinerNotes has an accessor named notes, you can do:

      my $cd = MyDB::Schema::CD->find(1);
      $cd->notes('Notes go here'); # set notes -- LinerNotes object is
                                   # created if it doesn't exist

accessor
    Specifies the type of accessor that should be created for the relationship. Valid values are "single" (for when there is only a single related object), "multi" (when there can be many), and "filter" (for when there is a single related object, but you also want the relationship accessor to double as a column accessor). For "multi" accessors, an add_to_* method is also created, which calls "create_related" for the relationship.

is_foreign_key_constraint
    If you are using SQL::Translator to create SQL for you and you find that it is creating constraints where it shouldn't, or not creating them where it should, set this attribute to a true or false value to override the detection of when to create constraints.

  register_relationship

Arguments: $relname, $rel_info

Registers a relationship on the class. This is called internally by DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.

  related_resultset

Arguments: $relationship_name
Return Value: $related_resultset

  $rs = $cd->related_resultset('artist');

Returns a DBIx::Class::ResultSet for the relationship named $relationship_name.

  search_related
  @objects = $rs->search_related('relname', $cond, $attrs);
  $objects_rs = $rs->search_related('relname', $cond, $attrs);

Run a search on a related resultset. The search will be restricted to the item or items represented by the DBIx::Class::ResultSet it was called upon. This method can be called on a ResultSet, a Row or a ResultSource class.

  search_related_rs
  ( $objects_rs ) = $rs->search_related_rs('relname', $cond, $attrs);

This method works exactly the same as search_related, except that it garauntees a restultset, even in list context.

  count_related
  $obj->count_related('relname', $cond, $attrs);

Returns the count of all the items in the related resultset, restricted by the current item or where conditions. Can be called on a "ResultSet" in DBIx::Class::Manual::Glossary or a "Row" in DBIx::Class::Manual::Glossary object.

  new_related
  my $new_obj = $obj->new_related('relname', \%col_data);

Create a new item of the related foreign class. If called on a Row object, it will magically set any foreign key columns of the new object to the related primary key columns of the source object for you. The newly created item will not be saved into your storage until you call "insert" in DBIx::Class::Row on it.

  create_related
  my $new_obj = $obj->create_related('relname', \%col_data);

Creates a new item, similarly to new_related, and also inserts the item's data into your storage medium. See the distinction between "create" and "new" in DBIx::Class::ResultSet for details.

  find_related
  my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals);

Attempt to find a related object using its primary key or unique constraints. See "find" in DBIx::Class::ResultSet for details.

  find_or_new_related
  my $new_obj = $obj->find_or_new_related('relname', \%col_data);

Find an item of a related class. If none exists, instantiate a new item of the related class. The object will not be saved into your storage until you call "insert" in DBIx::Class::Row on it.

  find_or_create_related
  my $new_obj = $obj->find_or_create_related('relname', \%col_data);

Find or create an item of a related class. See "find_or_create" in DBIx::Class::ResultSet for details.

  update_or_create_related
  my $updated_item = $obj->update_or_create_related('relname', \%col_data, \%attrs?);

Update or create an item of a related class. See "update_or_create" in DBIx::Class::ResultSet for details.

  set_from_related
  $book->set_from_related('author', $author_obj);
  $book->author($author_obj);                      ## same thing

Set column values on the current object, using related values from the given related object. This is used to associate previously separate objects, for example, to set the correct author for a book, find the Author object, then call set_from_related on the book.

This is called internally when you pass existing objects as values to "create" in DBIx::Class::ResultSet, or pass an object to a belongs_to acessor.

The columns are only set in the local copy of the object, call "update" to set them in the storage.

  update_from_related
  $book->update_from_related('author', $author_obj);

The same as "set_from_related", but the changes are immediately updated in storage.

  delete_related
  $obj->delete_related('relname', $cond, $attrs);

Delete any related item subject to the given conditions.

  add_to_$rel
Currently only available for "has_many", "many-to-many" and 'multi' type relationships.

Arguments: ($foreign_vals | $obj), $link_vals?

  my $role = $schema->resultset('Role')->find(1);
  $actor->add_to_roles($role);
      # creates a My::DBIC::Schema::ActorRoles linking table row object

  $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
      # creates a new My::DBIC::Schema::Role row object and the linking table
      # object with an extra column in the link

Adds a linking table object for $obj or $foreign_vals. If the first argument is a hash reference, the related object is created first with the column values in the hash. If an object reference is given, just the linking table object is created. In either case, any additional column values for the linking table object can be specified in $link_vals.

  set_$rel
Currently only available for "many-to-many" relationships.

Arguments: (\@hashrefs | \@objs)

  my $actor = $schema->resultset('Actor')->find(1);
  my @roles = $schema->resultset('Role')->search({ role =>
     { '-in' -> ['Fred', 'Barney'] } } );

  $actor->set_roles(\@roles);
     # Replaces all of $actor's previous roles with the two named

Replace all the related objects with the given reference to a list of objects. This does a "delete" on the link table resultset to remove the association between the current object and all related objects, then calls "add_to_$rel" repeatedly to link all the new objects.

Note that this means that this method will not delete any objects in the table on the right side of the relation, merely that it will delete the link between them.

Due to a mistake in the original implementation of this method, it will also accept a list of objects or hash references. This is deprecated and will be removed in a future version.

  remove_from_$rel
Currently only available for "many-to-many" relationships.

Arguments: $obj

  my $role = $schema->resultset('Role')->find(1);
  $actor->remove_from_roles($role);
      # removes $role's My::DBIC::Schema::ActorRoles linking table row object

Removes the link between the current object and the related object. Note that the related object itself won't be deleted unless you call ->delete() on it. This method just removes the link between the two objects.

AUTHORS
Matt S. Trout <mst@shadowcatsystems.co.uk>

LICENSE
You may distribute this code under the same terms as Perl itself.