fix new_related on uninserted objects to handle has_manys correctly

[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Relationship.pm

diff --git a/lib/DBIx/Class/Relationship.pm b/lib/DBIx/Class/Relationship.pm
index cb1fa54..8de8cc0 100644 (file)
--- a/lib/DBIx/Class/Relationship.pm
+++ b/lib/DBIx/Class/Relationship.pm
@@ -222,12 +222,13 @@ methods and valid relationship attributes.
 
 =back
 
-Creates a one-to-many relationship, where the corresponding elements of the
-foreign class store the calling class's primary key in one (or more) of its
-columns. This relationship defaults to using C<$accessor_name> as the foreign
-key in C<$related_class> to resolve the join, unless C<$foreign_key_column>
-specifies the foreign key column in C<$related_class> or C<cond> specifies a
-reference to a join condition hash.
+Creates a one-to-many relationship, where the corresponding elements
+of the foreign class store the calling class's primary key in one (or
+more) of its columns. This relationship defaults to using the end of
+this classes namespace as the foreign key in C<$related_class> to
+resolve the join, unless C<$foreign_key_column> specifies the foreign
+key column in C<$related_class> or C<cond> specifies a reference to a
+join condition hash.
 
 =over
 
@@ -269,28 +270,31 @@ OR condition.
   My::Schema::Item->has_many('rels', 'My::Schema::Relationships',
                              [ { 'foreign.LItemID' => 'self.ID' },
                                { 'foreign.RItemID' => 'self.ID'} ]);
+
 =back
 
   # in an Author class (where Author has_many Books)
+  # assuming related class is storing our PK in "author_id"
   My::DBIC::Schema::Author->has_many(
     books => 
     'My::DBIC::Schema::Book', 
     'author_id'
   );
 
-  # OR (same result, assuming related_class is storing our PK)
+  # OR (same result)
   My::DBIC::Schema::Author->has_many(
     books => 
     'My::DBIC::Schema::Book', 
+    { 'foreign.author_id' => 'self.id' },
   );
-
-  # OR (same result)
+  
+  # OR (similar result, assuming related_class is storing our PK, in "author")
+  # (the "author" is guessed at from "Author" in the class namespace)
   My::DBIC::Schema::Author->has_many(
     books => 
     'My::DBIC::Schema::Book', 
-    { 'foreign.author_id' => 'self.id' },
   );
-  
+
 
   # Usage
   # resultset of Books belonging to author 
@@ -326,9 +330,12 @@ L<DBIx::Class::Relationship::Base/"create_related">.
 
 If you delete an object in a class with a C<has_many> relationship, all
 the related objects will be deleted as well.  To turn this behaviour off,
-pass C<< cascade_delete => 0 >> in the C<attr> hashref. However, any
-database-level cascade or restrict will take precedence over a
-DBIx-Class-based cascading delete.
+pass C<< cascade_delete => 0 >> in the C<$attr> hashref.
+
+The cascaded operations are performed after the requested delete or
+update, so if your database has a constraint on the relationship, it
+will have deleted/updated the related records or raised an exception
+before DBIx::Class gets to perform the cascaded operation.
 
 If you copy an object in a class with a C<has_many> relationship, all
 the related objects will be copied as well. To turn this behaviour off,
@@ -379,7 +386,7 @@ OR
 =item cond
 
 A hashref where the keys are C<foreign.$column_on_related_table> and
-the values are C<self.$foreign_key_column>. This is useful for
+the values are C<self.$matching_column>. This is useful for
 relations that are across multiple columns.
 
 =back
@@ -410,8 +417,12 @@ relations that are across multiple columns.
 If you update or delete an object in a class with a C<might_have>
 relationship, the related object will be updated or deleted as well. To
 turn off this behavior, add C<< cascade_delete => 0 >> to the C<$attr>
-hashref. Any database-level update or delete constraints will override
-this behavior.
+hashref.
+
+The cascaded operations are performed after the requested delete or
+update, so if your database has a constraint on the relationship, it
+will have deleted/updated the related records or raised an exception
+before DBIx::Class gets to perform the cascaded operation.
 
 See L<DBIx::Class::Relationship::Base> for documentation on relationship
 methods and valid relationship attributes.
@@ -457,7 +468,7 @@ OR
 =item cond
 
 A hashref where the keys are C<foreign.$column_on_related_table> and
-the values are C<self.$foreign_key_column>. This is useful for
+the values are C<self.$matching_column>. This is useful for
 relations that are across multiple columns.
 
 =back