DBD::Safe - keep safe connection to DB
version 0.06
use DBI; my $dbh = DBI->connect( 'DBI:Safe:', undef, undef, { dbi_connect_args => [$dsn, $user, $password, $args] } );
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 an exception if reconnection is needed during the transaction.
CPAN contains modules with similar functionality. On the first place it is a DBIx::Connector, also see DBIx::HA and DBIx::DWIW. 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 in a tons of existed code, you must refactor all this code where you use database connections.
$conn->dbh
DBD::Safe has a transparent interface. You just need to replace connect() options and after this you can use it as usual database handler.
connect()
connect
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 are passed in the $dbd_safe_args hashref. This hashref can have following keys:
$dbd_safe_args
It is an arrayref with arguments for DBI->connect() which you pass when you use DBI without DBD::Safe. These arguments will be used for (re)connection to your database.
DBI->connect()
Instead of passing dbi_connect_args you can pass coderef that will be called during (re)connection. This coderef must return database handler. Using connect_cb you can switch to another replica in case of disconnection or implement another logic.
dbi_connect_args
connect_cb
You must pass one of dbi_connect_args or connect_cb.
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 retry_cb. 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 sleep() in this callback depending on number of trials.
retry_cb
sleep()
Callback that additionally checks if reconnection is necessary. Input argument is a $dbh handler, output - true or false. For example, you can use this callback to reconnect every N seconds.
$dbh
x_safe_get_dbh
If you have DBI with version >= 1.54, then you can explicitly call
my $real_dbh = $safe_dbh->x_safe_get_dbh;
This method will return real database handler that uses in the current time.
If you have DBI with version < 1.54, you can call
my $real_dbh = $safe_dbh->func('x_safe_get_dbh');
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).
http://github.com/tadam/DBD-Safe, DBIx::Connector, DBIx::HA, DBIx::DWIW.
Yury Zavarin <yury.zavarin@gmail.com>
This software is copyright (c) 2012 by Yury Zavarin.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install DBD::Safe, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DBD::Safe
CPAN shell
perl -MCPAN -e shell install DBD::Safe
For more information on module installation, please visit the detailed CPAN module installation guide.