Merge pull request #4 from berekuk/master

POD improvements, version bump

Changes

@@ -1,6 +1,9 @@
 Revision history for DBD-Safe
 
 {{$NEXT}}
+
+0.06    2012-07-19
+        - FETCH/STORE attributes doesn't call stay_connected()
         - is_connected() now pings database once, not twice
 
 0.04    2010-11-30

dist.ini

@@ -1,5 +1,5 @@
 name    = DBD-Safe
-version = 0.05
+version = 0.06
 author  = Yury Zavarin <yury.zavarin@gmail.com>
 license = Perl_5
 copyright_holder = Yury Zavarin

lib/DBD/Safe.pm

@@ -15,26 +15,26 @@ use warnings;
 
 =head1 DESCRIPTION
 
-DBD::Safe is an abstract DBI driver that helps you to keep safe connection to
-your database. Its purpose is reconnection to database when connection was corrupted.
+DBD::Safe is an abstract DBI driver that helps you to keep a safe connection to
+your database. Its purpose is to reconnect to the database when connection becomes corrupted.
 DBD::Safe makes reconnection in the following cases:
 
   - connection was dropped (usually occurs in long-running processes)
   - process was forked or threaded
 
-DBD::Safe throws exception if reconnection needed during the transaction.
+DBD::Safe throws an exception if reconnection is needed during the transaction.
 
 =head1 WHY YET ANOTHER SOLUTION?
 
 CPAN contains modules with similar functionality. On the first place it is a
 L<DBIx::Connector>, also see L<DBIx::HA> and L<DBIx::DWIW>.
-But DBIx::Connector and DBIx::DWIW assumes own interface for interacting with
+But DBIx::Connector and DBIx::DWIW assume their own interface for interacting with
 database. If you are going to use DBIx::Connector you must explicitly call
-$conn->dbh to get a real dbh connection. And if you want to add some fault tolerance
+C<< $conn->dbh >> to get a real dbh connection. And if you want to add some fault tolerance
 in a tons of existed code, you must refactor all this code where you use database
 connections.
 
-DBD::Safe have a transparent interface. You just need to replace C<connect()> options
+DBD::Safe has a transparent interface. You just need to replace C<connect()> options
 and after this you can use it as usual database handler.
 
 =head1 METHODS
@@ -47,16 +47,16 @@ For using DBD::Safe use DBI in a such manner:
 
   my $dbh = DBI->connect('DBI:Safe:', undef, undef, $dbd_safe_args);
 
-All arguments for DBD::Safe passes in the C<$dbd_safe_args> hashref.
+All arguments for DBD::Safe are passed in the C<$dbd_safe_args> hashref.
 This hashref can have following keys:
 
 =over
 
 =item I<dbi_connect_args>
 
-It is an arrayref with arguments for DBI->connect() which you passes when you
+It is an arrayref with arguments for C<< DBI->connect() >> which you pass when you
 use DBI without DBD::Safe. These arguments will be used for (re)connection to
-your database
+your database.
 
 =item I<connect_cb>
 
@@ -65,22 +65,22 @@ during (re)connection. This coderef must return database handler. Using
 C<connect_cb> you can switch to another replica in case of disconnection or
 implement another logic.
 
-You must pass any of C<dbi_connect_args> or C<connect_cb>.
+You must pass one of C<dbi_connect_args> or C<connect_cb>.
 
 =item I<retry_cb>
 
-This callback uses every time when DBD::Safe decides that reconnection needed.
-By default DBD::Safe make only one trie to reconnect and dies if it was
+This callback is used every time when DBD::Safe decides that reconnection needed.
+By default DBD::Safe make only one try to reconnect and dies if it was
 unsuccessful. You can override this using C<retry_cb>.
-This callback takes one argument - number of reconnection trie and returns
+This callback takes one argument - number of reconnection trials - and returns
 true or false (to make another reconnection attempt or not).
-For example, you can place some C<sleep()> in this callback depending on number of trie.
+For example, you can place some C<sleep()> in this callback depending on number of trials.
 
 =item I<reconnect_cb>
 
-Callback that additionally checks needness of reconnection. Input argument is a $dbh
+Callback that additionally checks if reconnection is necessary. Input argument is a C<$dbh>
 handler, output - true or false.
-For example, you can use this callback to make reconnection every N seconds.
+For example, you can use this callback to reconnect every N seconds.
 
 =back
 
@@ -98,6 +98,14 @@ If you have DBI with version < 1.54, you can call
 
 =back
 
+=head1 BUGS AND CAVEATS
+
+Connection is checked on each query. This can double your request execution time if all your requests are fast and network latency of your database is big enough.
+
+Statement objects are not safe. Once you've prepared the statement, it won't reconnect to the database transparently.
+
+There are no retries. If the request fails, it fails. This module just check that DB is alive *before* it tries to execute the statement. (Custom, per-query policies support is planned for the future releases).
+
 =head1 SEE ALSO
 
 L<http://github.com/tadam/DBD-Safe>,
@@ -169,8 +177,8 @@ sub connect {
     }
 
     my $retry_cb = sub {
-        my $trie = shift;
-        if ($trie == 1) {
+        my $try = shift;
+        if ($try == 1) {
             return 1;
         } else {
             return 0;
@@ -414,11 +422,11 @@ sub stay_connected {
             #return $dbh->set_err($DBI::stderr, "Reconnect needed when db in transaction");
         }
 
-        my $trie = 0;
+        my $try = 0;
         my $retry_cb = $dbh->FETCH('x_safe_retry_cb');
         while (1) {
-            $trie++;
-            my $can_connect = $retry_cb->($trie);
+            $try++;
+            my $can_connect = $retry_cb->($try);
             if ($can_connect) {
                 my $dbh = eval { real_connect($dbh) };
                 if (!$dbh) {

t/main.t

@@ -96,7 +96,7 @@ sub reconnect_threads : Test(1) {
 
 sub retry_cb : Test(1) {
     my $cb = sub {
-        my $trie = shift;
+        my $try = shift;
         return 0
     };
     dies_ok(sub { get_dbh({retry_cb => $cb}) }, "always negative retry_cb");