Fey::DBIManager::Source - Wraps a single DBI handle
my $source = Fey::DBIManager::Source->new( dbh => $dbh ); my $dbh = $source->dbh();
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.
This class provides the following methods:
Creates a new Fey::DBIManager::Source object. This method accepts a number of parameters.
The name of the source. This defaults to "default", which cooperates nicely with Fey::DBIManager.
An already connected DBI handle. Even if this is given, you still need to provide the relevant connection parameters such as "dsn".
A DBI DSN string. This is required.
The username and password for the source. These both default to an empty string.
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.
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".
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.
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.
These methods simply return the value of the specified attribute.
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".
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).
In order to provide consistency for Fey::ORM, sources enforce a set of standard attributes on DBI handles:
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.
Dave Rolsky, <autarch@urth.org>
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 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.
