/ 
Fey-DBIManager-0.08
River stage one • 4 direct dependents • 5 total dependents
/ Fey::DBIManager::Source

NAME

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

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.

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

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 and disconnect it. If the thread has changed, we just disconnect the handle.

Finally, we check $dbh->{Active] and call $dbh->ping(). If either of these is false, we disconnect the handle.

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

AUTHOR

Dave Rolsky, <autarch@urth.org>

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.

COPYRIGHT & LICENSE

Copyright 2006-2008 Dave Rolsky, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.