NAME

DBD::Safe - keep safe connection to DB

VERSION

version 0.06

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

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

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

METHODS

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:

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 must pass one of dbi_connect_args or connect_cb.

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

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 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');

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

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