Apache::DBI(3) User Contributed Perl Documentation Apache::DBI(3)NAMEApache::DBI - Initiate a persistent database connection
SYNOPSIS
# Configuration in httpd.conf or startup.pl:
PerlModule Apache::DBI # this comes before all other modules using DBI
Do NOT change anything in your scripts. The usage of this module is
absolutely transparent !
DESCRIPTION
This module initiates a persistent database connection.
The database access uses Perl's DBI. For supported DBI drivers see:
http://dbi.perl.org/
When loading the DBI module (do not confuse this with the Apache::DBI
module) it checks if the environment variable 'MOD_PERL' has been set
and if the module Apache::DBI has been loaded. In this case every
connect request will be forwarded to the Apache::DBI module. This
checks if a database handle from a previous connect request is already
stored and if this handle is still valid using the ping method. If
these two conditions are fulfilled it just returns the database handle.
The parameters defining the connection have to be exactly the same,
including the connect attributes! If there is no appropriate database
handle or if the ping method fails, a new connection is established and
the handle is stored for later re-use. There is no need to remove the
disconnect statements from your code. They won't do anything because
the Apache::DBI module overloads the disconnect method.
The Apache::DBI module still has a limitation: it keeps database
connections persistent on a per process basis. The problem is, if a
user accesses a database several times, the http requests will be
handled very likely by different processes. Every process needs to do
its own connect. It would be nice if all servers could share the
database handles, but currently this is not possible because of the
distinct memory-space of each process. Also it is not possible to
create a database handle upon startup of the httpd and then inherit
this handle to every subsequent server. This will cause clashes when
the handle is used by two processes at the same time. Apache::DBI has
built-in protection against this. It will not make a connection
persistent if it sees that it is being opened during the server
startup. This allows you to safely open a connection for grabbing data
needed at startup and disconnect it normally before the end of startup.
With this limitation in mind, there are scenarios, where the usage of
Apache::DBI is depreciated. Think about a heavy loaded Web-site where
every user connects to the database with a unique userid. Every server
would create many database handles each of which spawning a new backend
process. In a short time this would kill the web server.
Another problem are timeouts: some databases disconnect the client
after a certain period of inactivity. The module tries to validate the
database handle using the "ping()" method of the DBI-module. This
method returns true by default. Most DBI drivers have a working
"ping()" method, but if the driver you're using doesn't have one and
the database handle is no longer valid, you will get an error when
accessing the database. As a work-around you can try to add your own
"ping()" method using any database command which is cheap and safe, or
you can deactivate the usage of the ping method (see CONFIGURATION
below).
Here is a generalized ping method, which can be added to the driver
module:
package DBD::xxx::db; # ====== DATABASE ======
use strict;
sub ping {
my ($dbh) = @_;
my $ret = 0;
eval {
local $SIG{__DIE__} = sub { return (0); };
local $SIG{__WARN__} = sub { return (0); };
# adapt the select statement to your database:
$ret = $dbh->do('select 1');
};
return ($@) ? 0 : $ret;
}
Transactions: a standard DBI script will automatically perform a
rollback whenever the script exits. In the case of persistent database
connections, the database handle will not be destroyed and hence no
automatic rollback will occur. At a first glance it even seems possible
to handle a transaction over multiple requests. But this should be
avoided, because different requests are handled by different processes
and a process does not know the state of a specific transaction which
has been started by another process. In general, it is good practice to
perform an explicit commit or rollback at the end of every request. In
order to avoid inconsistencies in the database in case AutoCommit is
off and the script finishes without an explicit rollback, the
Apache::DBI module uses a PerlCleanupHandler to issue a rollback at the
end of every request. Note, that this CleanupHandler will only be used,
if the initial data_source sets AutoCommit = 0 or AutoCommit is turned
off, after the connect has been done (ie begin_work). However, because
a connection may have set other parameters, the handle is reset to its
initial connection state before it is returned for a second time.
This module plugs in a menu item for Apache::Status or Apache2::Status.
The menu lists the current database connections. It should be
considered incomplete because of the limitations explained above. It
shows the current database connections for one specific process, the
one which happens to serve the current request. Other processes might
have other database connections. The Apache::Status/Apache2::Status
module has to be loaded before the Apache::DBI module !
CONFIGURATION
The module should be loaded upon startup of the Apache daemon. Add the
following line to your httpd.conf or startup.pl:
PerlModule Apache::DBI
It is important, to load this module before any other modules using DBI
!
A common usage is to load the module in a startup file called via the
PerlRequire directive. See eg/startup.pl and eg/startup2.pl for
examples.
There are two configurations which are server-specific and which can be
done upon server startup:
Apache::DBI->connect_on_init($data_source, $username, $auth, \%attr)
This can be used as a simple way to have apache servers establish
connections on process startup.
Apache::DBI->setPingTimeOut($data_source, $timeout)
This configures the usage of the ping method, to validate a connection.
Setting the timeout to 0 will always validate the database connection
using the ping method (default). Setting the timeout < 0 will de-
activate the validation of the database handle. This can be used for
drivers, which do not implement the ping-method. Setting the timeout >
0 will ping the database only if the last access was more than timeout
seconds before.
For the menu item 'DBI connections' you need to call
Apache::Status/Apache2::Status BEFORE Apache::DBI ! For an example of
the configuration order see startup.pl.
To enable debugging the variable $Apache::DBI::DEBUG must be set. This
can either be done in startup.pl or in the user script. Setting the
variable to 1, just reports about a new connect. Setting the variable
to 2 enables full debug output.
PREREQUISITES
MOD_PERL 2.0
Apache::DBI version 0.96 and later should work under mod_perl 2.0 RC5
and later with httpd 2.0.49 and later.
Apache::DBI versions less than 1.00 are NO longer supported.
Additionally, mod_perl versions less then 2.0.0 are NO longer
supported.
MOD_PERL 1.0 Note that this module needs mod_perl-1.08 or higher,
apache_1.3.0 or higher and that mod_perl needs to be configured with
the appropriate call-back hooks:
PERL_CHILD_INIT=1 PERL_STACKED_HANDLERS=1
Apache::DBI v0.94 was the last version before dual mod_perl 2.x support
was begun. It still recommended that you use the latest version of
Apache::DBI because Apache::DBI versions less than 1.00 are NO longer
supported.
DO YOU NEED THIS MODULE?
Note that this module is intended for use in porting existing DBI code
to mod_perl, or writing code that can run under both mod_perl and CGI.
If you are using a database abstraction layer such as Class::DBI or
DBIx::Class that already manages persistent connections for you, there
is no need to use this module in addition. (Another popular choice,
Rose::DB::Object, can cooperate with Apache::DBI or use your own custom
connection handling.) If you are developing new code that is strictly
for use in mod_perl, you may choose to use "DBI->connect_cached()"
instead, but consider adding an automatic rollback after each request,
as described above.
SEE ALSO
Apache, mod_perl, DBI
AUTHORS
· Philip M. Gollucci <pgollucci@p6m7g8.com> is currently packaging
new releases.
Ask Bjoern Hansen <ask@develooper.com> packaged a large number of
releases.
· Edmund Mergl was the original author of Apache::DBI. It is now
supported and maintained by the modperl mailinglist, see the
mod_perl documentation for instructions on how to subscribe.
· mod_perl by Doug MacEachern.
· DBI by Tim Bunce <dbi-users-subscribe@perl.org>
COPYRIGHT
The Apache::DBI module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
perl v5.14.1 2011-10-07 Apache::DBI(3)