update cookbook and resultset docs

[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Manual / Cookbook.pod

diff --git a/lib/DBIx/Class/Manual/Cookbook.pod b/lib/DBIx/Class/Manual/Cookbook.pod
index 8bacb76..4f9fe63 100644 (file)
--- a/lib/DBIx/Class/Manual/Cookbook.pod
+++ b/lib/DBIx/Class/Manual/Cookbook.pod
@@ -1,21 +1,56 @@
 =head1 NAME 
 
-DBIx::Class::Manual::Cookbook - Misc receipes
+DBIx::Class::Manual::Cookbook - Misc recipes
 
-=over 4
+=head1 DESCRIPTION
 
-=item Input validation.
+Things that could be handy
 
-=item Using joins
+=head1 RECIPES
 
-=item Many-to-many relationships
+=head2 Disconnecting cleanly
+
+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
 
 This is not as easy as it could be, but it's possible. Here's an example to 
 illustrate:
 
        # Set up inherited connection information
        package MyApp::DBIC; 
-
        use base qw/DBIx::Class/;
 
        __PACKAGE__->load_components(qw/PK::Auto::SQLite Core DB/);
@@ -36,16 +71,16 @@ illustrate:
        sub books {
          my ($self) = @_;
          return MyApp::DBIC::Book->search(
-               { 'b2a.authID' => $self->authID }, { join => 'b2a' }
-         );
+               { 'b2a.authID' => $self->authID }, # WHERE clause
+               { join => 'b2a' } # join condition (part of search attrs)
            # 'b2a' refers to the relationship named earlier in the Author class.
                # 'b2a.authID' refers to the authID column of the b2a relationship,
                # which becomes accessible in the search by being joined.  
+         );
        }
 
        # define the link table class
        package MyApp::DBIC::Book2Author;
-
        use base qw/MyApp::DBIC/;
 
        __PACKAGE__->table('book2author');
@@ -56,7 +91,6 @@ illustrate:
        __PACKAGE__->belongs_to('bookID' => 'MyApp::DBIC::Book');
 
        package MyApp::DBIC::Book;
-
        use base qw/MyApp::DBIC/;
 
        __PACKAGE__->table('books');
@@ -69,15 +103,11 @@ illustrate:
         my ($self) = @_;
         return MyApp::DBIC::Author->search(
           { 'b2a.bookID' => $self->bookID }, # WHERE clause
-          { join => 'b2a' }); # Join condition
+          { join => 'b2a' }); # join condition (part of search attrs)
        }
 
        # So the above search returns an author record where the bookID field of the
        # book2author table equals the bookID of the books (using the bookID 
        # relationship table
 
-=item Advanced Exception handling
-
-=item Transactions
-
 =back