/ 
DBIx-HA-0.55
River stage zero No dependents
/ DBIx::HA

NAME

DBIx::HA - High Availability package for DBI

SYNOPSIS

use DBIx::HA;

$connect_attributes = {
        syb_flush_finish => 1,
        AutoCommit => 1,
        ChopBlanks => 1,
        PrintError => 0,
        RaiseError => 0,
        RootClass  => 'DBIx::HA'
        };

$DATABASE::conf{'test'} = {
   max_retries => 2,
   db_stack => [
       [ 'dbi:Sybase:server=prod1;database=test', 'user1', 'password1', $connect_attributes ],
       [ 'dbi:Sybase:server=prod2;database=test', 'user2', 'password2', $connect_attributes ],
       [ 'dbi:Sybase:server=prod3;database=test', 'user3', 'password3', $connect_attributes ],
       ],
   pingtimeout     => -1,
   failoverlevel   => 'application',
   connecttimeout  => 1,
   executetimeout  => 8,
   callback_function => \&MyCallbackFunction,
   };

DBIx::HA->initialize();
$dbh = DBIx::HA->connect('test');
   
$sth = $dbh->prepare($statement);
$rv = $sth->execute;

DESCRIPTION

DBIx::HA is a High Availability module for DBI. It is implemented by overloading the DBI connect, prepare and execute methods and can be seamlessly used without code modification except for initialization.

DBIx::HA also works seamlessly with Apache::DBI when available, and ensures that cached database handles in the Apache::DBI module are properly released when failing over.

Features of DBIx::HA are:

multiple failovers

Should a datasource become unavailable, queries are automatically sent to the next available datasource in a user-configured datasource stack. All subsequent queries continue to hit the failover server until reinitialized. This ensures that a failed datasource can be properly brought back online before it is put back in service.

timeouts

Database calls are wrapped in user-configurable timeouts. Connect and execute timeouts are handled independently.

configurable retries

Queries can be retried n times before a datasource is considered failed.

callback function

A user-defined callback function can be called upon abnormal failure and disconnection from a datasource in order to clean locally cached handles and perform other housekeeping tasks.

inter-process automatic failover under mod_perl

Failover can be triggered for a single process or a set of processes at the application level. Specifically designed for Apache's multi-process model, if one mod_perl process triggers a failover, it is propagated to all other mod_perl processes using the same database handle.

DBIx::HA was designed primarily for reliability and speed. Functionality that would compromise speed was not considered. This module has been tested extensively at very high loads in the Apache/mod_perl/Sybase environment.

CONFIGURATION

The hash %DATABASE::conf is currently the configuration repository for DBIx::HA. It must be manually and directly populated by the user prior to initialization and usage of DBIx::HA.

Each key of %DATABASE::conf is the name of a virtual database handle. The corresponding value is a hashref with the following keys:

db_stack REQUIRED

db_stack is an arrayref of arrayrefs. Each entry is of the format:

[ $dsn, $username, $password, \%connection_attributes ]

See the DBI documentation for more information. The order of the db_stack entries is very important. It determines the order by which each dsn will be tried upon triggering a failover. The first entry is the main dsn that will be used at start.

max_retries REQUIRED

max_retries takes an integer > 0 as value. It determines the number of times a datasource will be retried upon failure. It is NOT reset upon success unless the next datasource is reached. For example, if datasource #1 was already retried once before, and max_retries is 3, if datasource #1 can't be reached twice in a row then _reconnect() will reset the number of tries and go to datasource #2 if available.

pingtimeout ( DEFAULT: -1 )

this is only useful in conjunction with Apache::DBI. The default of -1 disables pinging the datasource. It is recommended not to modify it. See Apache::DBI for more information on ping timeouts. Timeout is in seconds.

failoverlevel ( DEFAULT: process )

failoverlevel determines whether a process will notify its sisters when fails over to another datasource.

process

no notification is made, and each process independently manages its datasource availability. Within a mod_perl environment, this means that each Apache process could be potentially hitting a different physical database server.

application

a file-based interprocess communication is used to notify Apache/mod_perl processes of the currently active datasource. This allows all processes to fail over near-simultaneously. A process in the middle of an execute will do it on the next call to prepare or execute. This is only available under mod_perl.

connecttimeout ( DEFAULT: 5 )

timeout for connecting to a datasource, in seconds.

executetimeout ( DEFAULT: 10 )

timeout for execution of a statement, in seconds.

callback_function ( DEFAULT: none )

reference to a function to call whenever the datasource is changed due to a failover. See the TIPS sections for a usage example.

USER METHODS

These methods provide a user interface to DBIx::HA.

initialize ()

This method is called as a static method after database configuration is done. At this point, database configuration resides in the %DATABASE::conf hash that needs to be properly populated. Later revisions of DBIx::HA will allow the passing of a reference to any configuration hash to initialize.

See a sample %DATABASE::conf in the SYNOPSIS section. That section creates an entry for the 'test' HA database handle, which is comprised of 3 physical database handles (prod1, prod2, prod3). 'prod1' is the main handle, while the other 2 are backup handles.

Add other HA database handles by creating more entries in %DATABASE::conf.

connect ( $dbname )

Static method to connect to the HA handle 'dbname'. There must be a valid entry for $DATABASE::conf{'dbname'}. Returns a standard DBI database handle.

prepare ( $dbh, $sql )

Overload of DBI::prepare(), with the same inputs and outputs.

execute ()

Overload of DBI::execute(), with the same inputs and outputs.

CLASS METHODS

These private methods are not intended to be called by the user, but are listed here for reference.

_readsharedfile ( $dbname )
_writesharedfile ( $dbname )
_getdbname ( $dsn )
_isactivedb ( $dsn )
_getnextdb ( $dsn )
_getApacheDBIidx ()
_reconnect ( $dsn )
_connect_with_timeout ( $dsn, $username, $auth, \%attrs )
_execute_with_timeout ( $dsn, $sth )

TIPS AND TECHNIQUES

using cached handles and the callback function

If you are using Apache::DBI, chances are that your setup is for high performance. So you probably are caching your DBI handles (dbh) within your application. If that is the case, then you must not forget to use the callback functionality of DBIx::HA. Your cached DBI handle MUST be updated if the HA module determines that your active database is unavailable. Here is an example of such a callback:

$DATABASE::conf{'test'}->{'callback_function'} => \&MyCallbackFunction;

sub MyCallbackFunction {

my $dbh		= shift;

my $dbname	= shift;

$cached_dbh{$dbname} = $dbh;
}

The above sets sets up the callback function, and creates the callback function so that it updates your locally available %cached_dbh hash of database handles to the currently active one.

load-balancing across read-only servers

It is very simple to load-balance across read-only database servers. Simply randomize or reorder the 'db_stack' entry in your database configuration on a per-process basis. This will make each process have its own set of primary and backup servers. Obviously you should never do that on a read-write environment with hot spares as you will be writing to the hot spares without writing to the primary server. Consider DBD::Multiplex for such an application.

manually setting the active datasource without downtime

Under mod_perl you can flip all Apache processes to a specific datasource by simply modifying the file DBIxHA_activedb_$dbname located in the /log directory in your Apache installation. Assuming that you are using failoverlevel 'application', all processes will switch to the datasource you define in that file as soon as they are ready to prepare or execute a statement.

BUGS

Currently %DATABASE::conf needs to be manually and directly populated. A proper interface needs to be built for it.

SEE ALSO

DBD::Multiplex for simultaneous writes to multiple data sources.

Apache::DBI for ping timeouts and caching of database handles.

AUTHOR

Henri Asseily <henri@asseily.com>

COPYRIGHT

Copyright (c) 2003-2004 Henri Asseily <henri@asseily.com>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.