__PACKAGE__->set_primary_key('cdid');
-__PACKAGE__->belongs_to('artist' => 'MyDatabase::Main::Result::Artist');
+__PACKAGE__->refers_to('artist' => 'MyDatabase::Main::Result::Artist');
__PACKAGE__->has_many('tracks' => 'MyDatabase::Main::Result::Track');
1;
__PACKAGE__->set_primary_key('trackid');
-__PACKAGE__->belongs_to('cd' => 'MyDatabase::Main::Result::Cd');
+__PACKAGE__->refers_to('cd' => 'MyDatabase::Main::Result::Cd');
1;
1;
-A result class to represent a CD, which belongs to an artist, in
+A result class to represent a CD, which refers to an artist, in
MyApp/Schema/Result/CD.pm:
package MyApp::Schema::Result::CD;
__PACKAGE__->table('cd');
__PACKAGE__->add_columns(qw/ cdid artistid title year /);
__PACKAGE__->set_primary_key('cdid');
- __PACKAGE__->belongs_to(artist => 'MyApp::Schema::Result::Artist', 'artistid');
+ __PACKAGE__->refers_to(artist => 'MyApp::Schema::Result::Artist', 'artistid');
1;
C<LinerNotes>:
# Relationships defined elsewhere:
- # CD->belongs_to('artist' => 'Artist');
+ # CD->refers_to('artist' => 'Artist');
# CD->has_one('liner_notes' => 'LinerNotes', 'cd');
my $rs = $schema->resultset('CD')->search(
{
notes:
# Relationship defined elsewhere:
- # LinerNotes->belongs_to('author' => 'Person');
+ # LinerNotes->refers_to('author' => 'Person');
my $rs = $schema->resultset('Artist')->search(
{
__PACKAGE__->table('user_address');
__PACKAGE__->add_columns(qw/user address/);
__PACKAGE__->set_primary_key(qw/user address/);
- __PACKAGE__->belongs_to('user' => 'My::User');
- __PACKAGE__->belongs_to('address' => 'My::Address');
+ __PACKAGE__->refers_to('user' => 'My::User');
+ __PACKAGE__->refers_to('address' => 'My::Address');
package My::Address;
use base 'DBIx::Class::Core';
And these rules exists:
one artist can have many cds
- one cd belongs to one artist
+ one cd refers to one artist
one cd can have many tracks
- one track belongs to one cd
+ one track refers to one cd
=head2 Installation
__PACKAGE__->table('cd');
__PACKAGE__->add_columns(qw/ cdid artist title/);
__PACKAGE__->set_primary_key('cdid');
- __PACKAGE__->belongs_to('artist' => 'MyDatabase::Main::Result::Artist');
+ __PACKAGE__->refers_to('artist' => 'MyDatabase::Main::Result::Artist');
__PACKAGE__->has_many('tracks' => 'MyDatabase::Main::Result::Track');
1;
__PACKAGE__->table('track');
__PACKAGE__->add_columns(qw/ trackid cd title /);
__PACKAGE__->set_primary_key('trackid');
- __PACKAGE__->belongs_to('cd' => 'MyDatabase::Main::Result::Cd');
+ __PACKAGE__->refers_to('cd' => 'MyDatabase::Main::Result::Cd');
1;
=item .. define a one-to-many relationship?
This is called a C<has_many> relationship on the one side, and a
-C<belongs_to> relationship on the many side. Currently these need to
+C<refers_to> relationship on the many side. Currently these need to
be set up individually on each side. See L<DBIx::Class::Relationship>
for details.
=item .. define a relationship where this table contains another table's primary key? (foreign key)
-Create a C<belongs_to> relationship for the field containing the
-foreign key. See L<DBIx::Class::Relationship/belongs_to>.
+Create a C<refers_to> relationship for the field containing the
+foreign key. See L<DBIx::Class::Relationship/refers_to>.
=item .. define a foreign key relationship where the key field may contain NULL?
-Just create a C<belongs_to> relationship, as above. If the column is
+Just create a C<refers_to> relationship, as above. If the column is
NULL then the inflation to the foreign object will not happen. This
has a side effect of not always fetching all the relevant data, if you
use a nullable foreign-key relationship in a JOIN, then you probably
=over 1
-=item L<DBIx::Class::Relationship/belongs_to>
+=item L<DBIx::Class::Relationship/refers_to>
=item L<DBIx::Class::Relationship/has_many>
=item books is a has_many
-=item address is a belongs_to which in turn belongs to state and city each
+=item address is a refers_to which in turn refers to state and city each
=item for this to work right state and city must mark abbreviation and name as unique
__PACKAGE__->set_primary_key( qw/ albumid artistid / );
-Define this class' relationships with other classes using either C<belongs_to>
+Define this class' relationships with other classes using either C<refers_to>
to describe a column which contains an ID of another Table, or C<has_many> to
make a predefined accessor for fetching objects that contain this Table's
foreign key:
And in C<MySchema::Tracks>:
- MySchema::Tracks->belongs_to('cd', 'MySchema::CD', 'CDID');
+ MySchema::Tracks->refers_to('cd', 'MySchema::CD', 'CDID');
There are several other types of relationships, they are more
comprehensively described in L<DBIx::Class::Relationship>.
In C<MySchema::Tracks>:
- MySchema::Tracks->belongs_to('artist', 'MySchema::Artist', 'ArtistID');
+ MySchema::Tracks->refers_to('artist', 'MySchema::Artist', 'ArtistID');
The search:
arguments of the method in order, separated by C<, >, preceded by the
text "Arguments: "
-Example (for the belongs_to relationship):
+Example (for the refers_to relationship):
=item Arguments: $accessor_name, $related_class, $fk_column|\%cond|\@cond?, \%attr?
...
__PACKAGE__->table('acl');
__PACKAGE__->add_columns(qw/ user_id /);
- __PACKAGE__->belongs_to( 'user' => 'My::Schema::User', 'user_id' );
+ __PACKAGE__->refers_to( 'user' => 'My::Schema::User', 'user_id' );
...
1;
'actor');
MyApp::Schema::Role->has_many('actorroles' => 'MyApp::Schema::ActorRole',
'role');
- MyApp::Schema::ActorRole->belongs_to('role' => 'MyApp::Schema::Role');
- MyApp::Schema::ActorRole->belongs_to('actor' => 'MyApp::Schema::Actor');
+ MyApp::Schema::ActorRole->refers_to('role' => 'MyApp::Schema::Role');
+ MyApp::Schema::ActorRole->refers_to('actor' => 'MyApp::Schema::Actor');
MyApp::Schema::Role->many_to_many('actors' => 'actorroles', 'actor');
MyApp::Schema::Actor->many_to_many('roles' => 'actorroles', 'role');
attributes that are allowed in the C<attrs> argument.
-=head2 belongs_to
+=head2 refers_to
=over 4
=back
# in a Book class (where Author has many Books)
- My::DBIC::Schema::Book->belongs_to(
+ My::DBIC::Schema::Book->refers_to(
author =>
'My::DBIC::Schema::Author',
'author_id'
);
# OR (same result)
- My::DBIC::Schema::Book->belongs_to(
+ My::DBIC::Schema::Book->refers_to(
author =>
'My::DBIC::Schema::Author',
{ 'foreign.author_id' => 'self.author_id' }
);
# OR (similar result but uglier accessor name)
- My::DBIC::Schema::Book->belongs_to(
+ My::DBIC::Schema::Book->refers_to(
author_id =>
'My::DBIC::Schema::Author'
);
If the relationship is optional -- i.e. the column containing the
-foreign key can be NULL -- then the belongs_to relationship does the
+foreign key can be NULL -- then the refers_to relationship does the
right thing. Thus, in the example above C<< $obj->author >> would
return C<undef>. However in this case you would probably want to set
the L<join_type|DBIx::Class::Relationship/join_type> attribute so that
declaration is shown below:
# in a Book class (where Author has_many Books)
- __PACKAGE__->belongs_to(
+ __PACKAGE__->refers_to(
author =>
'My::DBIC::Schema::Author',
'author',
);
-Cascading deletes are off by default on a C<belongs_to>
+Cascading deletes are off by default on a C<refers_to>
relationship. To turn them on, pass C<< cascade_delete => 1 >>
in the $attr hashref.
By default, DBIC will return undef and avoid querying the database if a
-C<belongs_to> accessor is called when any part of the foreign key IS NULL. To
+C<refers_to> accessor is called when any part of the foreign key IS NULL. To
disable this behavior, pass C<< undef_on_null_fk => 0 >> in the C<\%attrs>
hashref.
If you must be naughty, you can suppress the warning by setting
C<DBIC_DONT_VALIDATE_RELS> environment variable to a true value. Otherwise,
-you probably just meant to use C<DBIx::Class::Relationship/belongs_to>.
+you probably just meant to use C<DBIx::Class::Relationship/refers_to>.
=head2 has_one
=item foreign_rel_name
-This is the accessor_name of the belongs_to relationship in the link
+This is the accessor_name of the refers_to relationship in the link
table that we are bridging across (which gives us the table we are
bridging to).
My::DBIC::Schema::Actor->has_many( actor_roles =>
'My::DBIC::Schema::ActorRoles',
'actor' );
- My::DBIC::Schema::ActorRoles->belongs_to( role =>
+ My::DBIC::Schema::ActorRoles->refers_to( role =>
'My::DBIC::Schema::Role' );
- My::DBIC::Schema::ActorRoles->belongs_to( actor =>
+ My::DBIC::Schema::ActorRoles->refers_to( actor =>
'My::DBIC::Schema::Actor' );
My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles',
In the above example, ActorRoles is the link table class, and Role is the
foreign class. The C<$link_rel_name> parameter is the name of the accessor for
the has_many relationship from this table to the link table, and the
-C<$foreign_rel_name> parameter is the accessor for the belongs_to relationship
+C<$foreign_rel_name> parameter is the accessor for the refers_to relationship
from the link table to the foreign table.
To use many_to_many, existing relationships from the original table to the link
The 'proxy' attribute can be used to retrieve values, and to perform
updates if the relationship has 'cascade_update' set. The 'might_have'
and 'has_one' relationships have this set by default; if you want a proxy
-to update across a 'belongs_to' relationship, you must set the attribute
+to update across a 'refers_to' relationship, you must set the attribute
yourself.
=over 4
$cd->notes('Notes go here'); # set notes -- LinerNotes object is
# created if it doesn't exist
-For a 'belongs_to relationship, note the 'cascade_update':
+For a 'refers_to relationship, note the 'cascade_update':
- MyApp::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd,
+ MyApp::Schema::Track->refers_to( cd => 'DBICTest::Schema::CD', 'cd,
{ proxy => ['title'], cascade_update => 1 }
);
$track->title('New Title');
A hashref where each key is the accessor you want installed in the main class,
and its value is the name of the original in the fireign class.
- MyApp::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd', {
+ MyApp::Schema::Track->refers_to( cd => 'DBICTest::Schema::CD', 'cd', {
proxy => { cd_title => 'title' },
});
NOTE: you can pass a nested struct too, for example:
- MyApp::Schema::Track->belongs_to( cd => 'DBICTest::Schema::CD', 'cd', {
+ MyApp::Schema::Track->refers_to( cd => 'DBICTest::Schema::CD', 'cd', {
proxy => [ 'year', { cd_title => 'title' } ],
});
per-relationship basis by supplying C<< cascade_update => 0 >> in
the relationship attributes.
-The C<belongs_to> relationship does not update across relationships
-by default, so if you have a 'proxy' attribute on a belongs_to and want to
+The C<refers_to> relationship does not update across relationships
+by default, so if you have a 'proxy' attribute on a refers_to and want to
use 'update' on it, you muse set C<< cascade_update => 1 >>.
This is not a RDMS style cascade update - it purely means that when
attributes to explicitly set the desired C<ON DELETE> or C<ON UPDATE> constraint
type. If not supplied the SQLT parser will attempt to infer the constraint type by
interrogating the attributes of the B<opposite> relationship. For any 'multi'
-relationship with C<< cascade_delete => 1 >>, the corresponding belongs_to
+relationship with C<< cascade_delete => 1 >>, the corresponding refers_to
relationship will be created with an C<ON DELETE CASCADE> constraint. For any
-relationship bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint
+relationship bearing C<< cascade_copy => 1 >> the resulting refers_to constraint
will be C<ON UPDATE CASCADE>. If you wish to disable this autodetection, and just
use the RDBMS' default constraint type, pass C<< on_delete => undef >> or
C<< on_delete => '' >>, and the same for C<on_update> respectively.
call set_from_related on the book.
This is called internally when you pass existing objects as values to
-L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
+L<DBIx::Class::ResultSet/create>, or pass an object to a refers_to accessor.
The columns are only set in the local copy of the object, call L</update> to
set them in the storage.
);
Example of creating a new row and also creating a row in a related
-C<belongs_to> resultset. Note Hashref.
+C<refers_to> resultset. Note Hashref.
$cd_rs->create({
title=>"Music for Silly Walks",
__PACKAGE__->table('track');
__PACKAGE__->add_columns(qw/trackid cd position title/);
__PACKAGE__->set_primary_key('trackid');
- __PACKAGE__->belongs_to(cd => 'MyApp::Schema::CD');
+ __PACKAGE__->refers_to(cd => 'MyApp::Schema::CD');
1;
# In your application
tracks.
# Assuming:
- My::Schema::CD->belongs_to( artist => 'My::Schema::Artist' );
+ My::Schema::CD->refers_to( artist => 'My::Schema::Artist' );
My::Schema::CD->might_have( liner_note => 'My::Schema::LinerNotes' );
My::Schema::CD->has_one( cover_image => 'My::Schema::Artwork' );
My::Schema::CD->has_many( tracks => 'My::Schema::Track' );
- My::Schema::Artist->belongs_to( record_label => 'My::Schema::RecordLabel' );
+ My::Schema::Artist->refers_to( record_label => 'My::Schema::RecordLabel' );
My::Schema::Track->has_many( guests => 'My::Schema::Guest' );
undef,
{
prefetch => [
- { artist => 'record_label'}, # belongs_to => belongs_to
+ { artist => 'record_label'}, # refers_to => refers_to
'liner_note', # might_have
'cover_image', # has_one
{ tracks => 'guests' }, # has_many => has_many
{
prefetch => [
'tracks', # has_many
- { cd_to_producer => 'producer' }, # has_many => belongs_to (i.e. m2m)
+ { cd_to_producer => 'producer' }, # has_many => refers_to (i.e. m2m)
]
}
);
points to, looking for one whose condition is the reverse of the
condition on this relationship.
-A common use of this is to find the name of the C<belongs_to> relation
+A common use of this is to find the name of the C<refers_to> relation
opposing a C<has_many> relation. For definition of these look in
L<DBIx::Class::Relationship>.
L<create|DBIx::Class::ResultSet/create>, L<find|DBIx::Class::ResultSet/find>,
L<next|DBIx::Class::ResultSet/next> and L<all|DBIx::Class::ResultSet/all> methods,
as well as invocations of 'single' (
-L<belongs_to|DBIx::Class::Relationship/belongs_to>,
+L<refers_to|DBIx::Class::Relationship/refers_to>,
L<has_one|DBIx::Class::Relationship/has_one> or
L<might_have|DBIx::Class::Relationship/might_have>)
relationship accessors of L<Result|DBIx::Class::Manual::ResultClass> objects.
projects / dbsrgits/DBIx-Class.git / commitdiff