NAME

Fey::DBIManager::Source - Wraps a single DBI handle

VERSION

version 0.16

SYNOPSIS

my $source = Fey::DBIManager::Source->new( dbh => $dbh );

my $dbh = $source->dbh();

DESCRIPTION

A Fey::DBIManager::Source object provides a wrapper around a DBI handle which does things like ensure that handles are recreated properly after a fork.

A source can be created from an existing DBI handle, or from parameters such as the dsn and authentication info.

METHODS

This class provides the following methods:

Fey::DBIManager::Source->new(...)

Creates a new Fey::DBIManager::Source object. This method accepts a number of parameters.

• name

  The name of the source. This defaults to "default", which cooperates nicely with Fey::DBIManager.

• dbh

  An already connected DBI handle. Even if this is given, you still need to provide the relevant connection parameters such as "dsn".

• dsn

  A DBI DSN string. This is required.

• username

• password

  The username and password for the source. These both default to an empty string.

• attributes

  A hash reference of attributes to be passed to DBI->connect(). Note that some attributes are set for all handles. See "REQUIRED ATTRIBUTES" for more details. This attribute is optional.

• post_connect

  This is an optional subroutine reference which will be called after a handle is created with DBI->connect(). This is a handy way to set connection info or to set driver-specific attributes like "mysql_enable_utf8" or "pg_auto_escape".

• auto_refresh

  A boolean value. The default is true, which means that whenever you call $source->dbh(), the source ensures that the database handle is still active. See "HANDLE FRESHNESS" for more details.

• ping_interval

  An integer value representing the minimum number of seconds between successive pings of the database handle. See "HANDLE FRESHNESS" for more details. The default value is 60 (seconds). A value of 0 causes the source to ping the database handle each time you call $source->dbh().

  If you explicitly set this value to undef, then the database will never be pinged.

  Note that if "auto_refresh" is false, this attribute is meaningless.

$source->dbh()

Returns a database handle for the source. If you did not pass a handle to the constructor, this may create a new handle. If auto_refresh is true, this may cause a new handle to be created. See "HANDLE FRESHNESS" for more details.

$source->dsn()

$source->username()

$source->password()

$source->post_connect()

$source->auto_connect()

These methods simply return the value of the specified attribute.

$source->attributes()

This method returns attributes hash reference for the source. This will be a combination of any attributes passed to the constructor plus the "REQUIRED ATTRIBUTES".

$source->allows_nested_transactions()

Returns a boolean indicating whether or not the database to which the source connects supports nested transactions. It does this by trying to issue two calls to $dbh->begin_work() followed by two calls to $dbh->rollback() (in an eval block).

$source->clone(...)

Returns a new source which is a clone of the original. If no name is provided, it is created as "Clone of <original name>". The cloned source does not share the original's database handle.

Any arguments passed to this method are passed to the constructor when creating the clone.

REQUIRED ATTRIBUTES

In order to provide consistency for Fey::ORM, sources enforce a set of standard attributes on DBI handles:

• AutoCommit => 1

• RaiseError => 1

• PrintError => 0

• PrintWarn => 1

• ShowErrorStatement => 1

HANDLE FRESHNESS

If auto_refresh is true for a source, then every call to $source->dbh() incurs the cost of a "freshness" check. The upside of this is that it will just work in the face of forks, threading, and lost connections.

First, we check to see if the pid has changed since the handle was created. If it has, we set InactiveDestroy to true in the handle before making a new handle. If the thread has changed, we just make a new handle.

Next, we check $dbh->{Active] and, if this is false, we disconnect the handle.

Finally, we check that the handle has responded to $dbh->ping() within the past $source->ping_interval() seconds. If it hasn't, we call $dbh->ping() and, if it returns false, we disconnect the handle.

If the handle is not fresh, a new one is created.

BUGS

Please report any bugs or feature requests to bug-fey-dbimanager@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

AUTHOR

Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2011 by Dave Rolsky.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)