Provided by: libapache-dbi-perl_1.12-1_all bug

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://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 is
       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.