NAME

DBD::Safe - keeps safe database connection

VERSION

version 0.07

SYNOPSIS

use DBI;
my $dbh = DBI->connect(
    'DBI:Safe:', undef, undef,
    { dbi_connect_args => [$dsn, $user, $password, $args] }
);

DESCRIPTION

DBD::Safe is an abstract DBI driver that helps you to keep a safe database connection. 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.

WHY YET ANOTHER SOLUTION?

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 a 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 tons of existed code, you must refactor all this code where you use database connections.

DBD::Safe has a transparent interface. You just need to replace connect() options and after this you can use it as an usual database handler.

METHODS

connect

For using DBD::Safe use DBI in 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 the following keys:

dbi_connect_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.

connect_cb

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.

You have to pass either dbi_connect_args or connect_cb.

retry_cb

This callback is used every time when DBD::Safe decides that reconnection is needed. By default DBD::Safe does only one attempt 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. Return values indicates whether next reconnection attempt is needed or not. For example, you can place some sleep() in this callback depending on number of trials.

reconnect_cb

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.

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 is using at the moment.

If you have DBI with version < 1.54, you can call

my $real_dbh = $safe_dbh->func('x_safe_get_dbh');

BUGS AND CAVEATS

Connection is being checked on each query. This can double your request execution time if all your requests are fast and network latency to 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 a request fails, it fails. This module just checks that DB is alive *before* it tries to execute the statement. (Custom, per-query policies support is planned for the future releases).

SEE ALSO

http://github.com/tadam/DBD-Safe, DBIx::Connector, DBIx::HA, DBIx::DWIW.

AUTHOR

Yury Zavarin <yury.zavarin@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 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.