X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FRelationship.pm;h=427b5aaea4ac3aedb7092c0bc34a7cb1ce995a34;hb=2f7aa46c7cbfd235a26863459f80225a72a6e82e;hp=26a07ef0e6955394e73e03dbaca5f5ac5175c1c5;hpb=2dcff23ad7e34505eb42c7bcb6ae12ac5daa2c61;p=dbsrgits%2FDBIx-Class.git

diff --git a/lib/DBIx/Class/Relationship.pm b/lib/DBIx/Class/Relationship.pm
index 26a07ef..427b5aa 100644
--- a/lib/DBIx/Class/Relationship.pm
+++ b/lib/DBIx/Class/Relationship.pm
@@ -191,15 +191,16 @@ more info see L<DBIx::Class::Relationship::Base/condition>.
   # To retrieve the plain id if you used the ugly version:
   $book->get_column('author_id');
 
-
-If the relationship is optional -- i.e. the column containing the
-foreign key can be NULL -- then the belongs_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::Base/join_type> attribute so that
-a C<LEFT JOIN> is done, which makes complex resultsets involving
-C<join> or C<prefetch> operations work correctly.  The modified
-declaration is shown below:
+If some of the foreign key columns are
+L<nullable|DBIx::Class::ResultSource/is_nullable> you probably want to set
+the L<join_type|DBIx::Class::Relationship::Base/join_type> attribute to
+C<left> explicitly so that SQL expressing this relation is composed with
+a C<LEFT JOIN> (as opposed to C<INNER JOIN> which is default for
+L</belongs_to> relationships). This ensures that relationship traversal
+works consistently in all situations. (i.e. resultsets involving
+L<join|DBIx::Class::ResultSet/join> or
+L<prefetch|DBIx::Class::ResultSet/prefetch>).
+The modified declaration is shown below:
 
   # in a Book class (where Author has_many Books)
   __PACKAGE__->belongs_to(
@@ -209,7 +210,6 @@ declaration is shown below:
     { join_type => 'left' }
   );
 
-
 Cascading deletes are off by default on a C<belongs_to>
 relationship. To turn them on, pass C<< cascade_delete => 1 >>
 in the $attr hashref.