Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

POD improvements, version bump #4

Merged
merged 6 commits into from

2 participants

@berekuk
Collaborator

I also uploaded it to CPAN.
Do you intend to maintain this module further? If not, maybe you should give me commit bit here on github?

@tadam tadam merged commit 813a857 into tadam:master
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Jul 18, 2012
  1. @berekuk
  2. @berekuk

    POD improvements

    berekuk authored
  3. @berekuk
Commits on Jul 19, 2012
  1. @berekuk

    Merge branch 'refactorings'

    berekuk authored
  2. @berekuk

    "bugs and caveats" pod section

    berekuk authored
  3. @berekuk

    v0.06

    berekuk authored
            - FETCH/STORE attributes doesn't call stay_connected()
            - is_connected() now pings database once, not twice
This page is out of date. Refresh to see the latest.
Showing with 34 additions and 23 deletions.
  1. +3 −0  Changes
  2. +1 −1  dist.ini
  3. +29 −21 lib/DBD/Safe.pm
  4. +1 −1  t/main.t
View
3  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
View
2  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
View
50 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) {
View
2  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");
Something went wrong with that request. Please try again.