Apache::DBI

DBI(3)                User Contributed Perl Documentation               DBI(3)



NAME
       Apache::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://www.symbolstone.org/technology/perl/DBI/

       When loading the DBI module (do not confuse this with the Apache::DBI
       module) it looks if the environment variable GATEWAY_INTERFACE starts
       with 'CGI-Perl' and if the module Apache::DBI has been loaded. In this
       case every connect request will be forwarded to the Apache::DBI module.
       This looks 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 several times a database, the http requests will be
       handled very likely by different servers. Every server needs to do its
       own connect. It would be nice, if all servers could share the database
       handles. Currently this is not possible, because of the distinct name-
       space of every process. Also it is not possible to create a database
       handle upon startup of the httpd and then inheriting this handle to
       every subsequent server. This will cause clashes when the handle is
       used by two processes at the same time.

       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 time of inactivity. The module tries to validate the
       database handle using the ping-method of the DBI-module. This method
       returns true as default.  If the database handle is not valid and the
       driver has no implementation for the ping method, you will get an error
       when accessing the database. As a work-around you can try to replace
       the ping method by any database command, which is cheap and safe or you
       can deactivate the usage of the ping method (see CONFIGURATION below).

       Here is 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 occurs. At a first glance it seems even to be
       possible, to handle a transaction over multiple requests. But this
       should be avoided, because different requests are handled by different
       servers and a server does not know the state of a specific transaction
       which has been started by another server. In general it is good
       practice to perform an explicit commit or rollback at the end of every
       script. 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. It will not be
       used, if AutoCommit will be turned off, after the connect has been
       done.

       This module plugs in a menu item for Apache::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 server, the one which happens to
       serve the current request.  Other servers might have other database
       connections. The Apache::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 via the
       PerlRequire directive. See eg/startup.pl for an example.

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


SEE ALSO
       the Apache manpage, the mod_perl manpage, the DBI manpage

AUTHORS
       · mod_perl by Doug MacEachern <modperl@apache.org>

       · DBI by Tim Bunce <dbi-users@isc.org>

       · Apache::AuthenDBI by Edmund Mergl <E.Mergl@bawue.de>

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
















3rd Berkeley Distribution    perl 5.005, patch 03                       DBI(3)