NAME

 Fault::Dbh - Database Handle abstraction.

SYNOPSIS

 use Fault::Dbh;
        Fault::Dbh->init;
 $db  = Fault::Dbh->open ($db, $usr, $pass);
 $dbh = $db->dbh;
 $db->close;

Description

The Fault::Dbh Database handle abstraction centralizes the creation and destruction of a database handle for a connection to the database server. I do this to minimize the number of active socket connections to the database server. I have observed situations in which all available processes have been utilized, causing further access attempts to fail.

This is currently only coded to function on a single local MySQL database. If multiple databases are required, I will have to get fancier, perhaps a local hash of database names with handles attached.

The init method is supplied for use in forked environments. Since only a single database connection is created by open, no matter how many times you call it, you will get into very deep trouble if you open then fork and access the database from both processes. If you fork, use the init method as one of the first things you do in your child process. If you do not do this, do not come crying to me about the really weird random error messages and connection closures you are getting from your database.

If I wanted to, I could subclass the DBI::db handle itself, but I did not study enough of it to make sure I did not step on anything,

Error handling is currently minimal; virtually anything that goes wrong will cause the return of a pointer with a value of undef.

Examples

 use Fault::Dbh;
        Fault::Dbh->init;
 $db  = Fault::Dbh->open ("mydatabase","me","apassword");
 $dbh = $db->dbh;
 $db->close;

Class Variables (Internal)

 DBH            the database handle or undef
 DBHCNT         number of opens on this handle, zero if closed.

Instance Variables

None.

Class Methods

Fault::Dbh->init

Initialize the local database handles. This discards any handle which was previously opened. We need this because if we fork a process the old handle gets shared among parent and child processes and if any two attempt to communicate with the db at the same time...

If you are only working with a single process, you only need to use open and close. If you fork, you should init as one of the very first things you do in the new process.

$dbh = Fault::Dbh->open ($db, $usr, $pass)

Class method to create a new object to handle a connection to the local database server for $db as user $usr with password $pass. It only supports one localhost database at present. A new connection is opened only if the count of open connections is zero; otherwise it re-uses the currently open one.

It returns undef if it fails to make the requested connection.

Instance Methods

$dbh = $db->dbh

Return the database handle.

$db->close

Close this connection to the database server. It decrements the count of open connections and does the real disconnect if the count reaches zero.

Private Class Methods

 None.

Private Instance Methods

 None.

Errors and Warnings

 None.

KNOWN BUGS

 See TODO.

SEE ALSO

 DBI

AUTHOR

Dale Amon <amon@vnl.com>

cpanm Fault::Msg

perl -MCPAN -e shell
install Fault::Msg