From: David Kamholz <dkamholz@cpan.org>
Date: Sat, 10 Dec 2005 21:19:03 +0000 (+0000)
Subject: update cookbook and resultset docs
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=87980de749bd86e74b71f708237b9910790a9b87;p=dbsrgits%2FDBIx-Class-Historic.git

update cookbook and resultset docs
---

diff --git a/lib/DBIx/Class.pm b/lib/DBIx/Class.pm
index bbfdc17..2cd870c 100644
--- a/lib/DBIx/Class.pm
+++ b/lib/DBIx/Class.pm
@@ -8,7 +8,6 @@ use base qw/DBIx::Class::Componentised Class::Data::Inheritable/;
 
 $VERSION = '0.04001';
 
-
 1;
 
 =head1 NAME 
diff --git a/lib/DBIx/Class/Manual/Cookbook.pod b/lib/DBIx/Class/Manual/Cookbook.pod
index 57c2175..4f9fe63 100644
--- a/lib/DBIx/Class/Manual/Cookbook.pod
+++ b/lib/DBIx/Class/Manual/Cookbook.pod
@@ -8,9 +8,41 @@ Things that could be handy
 
 =head1 RECIPES
 
-=head2 Input validation.
+=head2 Disconnecting cleanly
 
-=head2 Using joins
+If you find yourself quitting an app with Control-C a lot during development,
+you might like to put the following signal handler in your main database
+class to make sure it disconnects cleanly:
+
+    $SIG{INT} = sub {
+        __PACKAGE__->storage->dbh->disconnect;
+    };
+
+=head2 Using joins and prefetch
+
+See L<DBIx::Class::ResultSet/Attributes>.
+
+=head2 Transactions
+
+As of version 0.04001, there is improved transaction support in
+L<DBIx::Class::Storage::DBI>. Here is an example of the recommended way to use it:
+
+    my $obj = Genus->find(12);
+    eval {
+        MyDB->tx_begin;
+        $obj->add_to_species({ name => 'troglodyte' });
+        $obj->wings(2);
+        $obj->update;
+        cromulate($obj); # can have a nested transation
+        MyDB->tx_commit;
+    };
+    if ($@) { eval { MyDB->tx_rollback } } # rollback might fail, too
+
+Currently, a nested commit will do nothing and a nested rollback will die.
+The code at each level must be sure to call rollback in the case of an error,
+to ensure that the rollback will propagate to the top level and be issued.
+Support for savepoints and for true nested transactions (for databases that
+support them) will hopefully be added in the future.
 
 =head2 Many-to-many relationships
 
@@ -78,8 +110,4 @@ illustrate:
 	# book2author table equals the bookID of the books (using the bookID 
 	# relationship table
 
-=head2 Advanced Exception handling
-
-=head2 Transactions
-
 =back
diff --git a/lib/DBIx/Class/ResultSet.pm b/lib/DBIx/Class/ResultSet.pm
index eae9193..597eef5 100644
--- a/lib/DBIx/Class/ResultSet.pm
+++ b/lib/DBIx/Class/ResultSet.pm
@@ -280,7 +280,7 @@ Which columns should be retrieved.
 
 =head2 join
 
-Contains a list of relations that should be joined for this query. Can also 
+Contains a list of relationships that should be joined for this query. Can also 
 contain a hash reference to refer to that relation's relations. So, if one column
 in your class C<belongs_to> foo and another C<belongs_to> bar, you can do
 C<< join => [qw/ foo bar /] >> to join both (and e.g. use them for C<order_by>).
@@ -288,6 +288,14 @@ If a foo contains many margles and you want to join those too, you can do
 C<< join => { foo => 'margle' } >>. If you want to fetch the columns from the
 related table as well, see C<prefetch> below.
 
+=head2 prefetch
+
+Contains a list of relationships that should be fetched along with the main 
+query (when they are accessed afterwards they will have already been
+"prefetched"). This is useful for when you know you will need the related
+object(s), because it saves a query. Currently limited to prefetching
+one relationship deep, so unlike C<join>, prefetch must be an arrayref.
+
 =head2 from 
 
 This attribute can contain a arrayref of elements. Each element can be another