Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Apache::DBI(3)	      User Contributed Perl Documentation	Apache::DBI(3)

       Apache::DBI - Initiate a	persistent database connection

	# Configuration	in httpd.conf or

	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 !

       This module initiates a persistent database connection.

       The database access uses	Perl's DBI. For	supported DBI drivers see:

       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

       Here is a generalized ping method, which	can be added to	the driver

	  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 !

       The module should be loaded upon	startup	of the Apache daemon.  Add the
       following line to your httpd.conf or

	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/	and eg/ for

       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

       To enable debugging the variable	$Apache::DBI::DEBUG must be set. This
       can either be done in	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.

   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

   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:

       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

       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.

       Apache, mod_perl, DBI

       o   Philip M. Gollucci <> is	currently packaging
	   new releases.

	   Ask Bjoern Hansen <> packaged a large number of

       o   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.

       o   mod_perl by Doug MacEachern.

       o   DBI by Tim Bunce <>

       The Apache::DBI module is free software;	you can	redistribute it	and/or
       modify it under the same	terms as Perl itself.

perl v5.32.0			  2013-06-12			Apache::DBI(3)


Want to link to this manual page? Use this URL:

home | help