view release on metacpan or  search on metacpan

lib/Apache/DBI.pm  view on Meta::CPAN

  use strict;
  sub disconnect {
      my $prefix = "$$ Apache::DBI            ";
      Apache::DBI::debug(2, "$prefix disconnect (overloaded)");
      1;
  }
  ;
}

# prepare menu item for Apache::Status
sub status_function {
    my($r, $q) = @_;

    my(@s) = qw(<TABLE><TR><TD>Datasource</TD><TD>Username</TD></TR>);
    for (keys %Connected) {
        push @s, '<TR><TD>',
            join('</TD><TD>',
                 (split($;, $_))[0,1]), "</TD></TR>\n";
    }
    push @s, '</TABLE>';

    \@s;
}

if (MP2) {
    if (Apache2::Module::loaded('Apache2::Status')) {
	    Apache2::Status->menu_item(
                                   'DBI' => 'DBI connections',
                                    \&status_function
                                  );
    }
}
else {
   if ($INC{'Apache.pm'}                       # is Apache.pm loaded?
       and Apache->can('module')               # really?
       and Apache->module('Apache::Status')) { # Apache::Status too?
       Apache::Status->menu_item(
                                'DBI' => 'DBI connections',
                                \&status_function
                                );
   }
}

1;

__END__


=head1 NAME

Apache::DBI - Initiate a persistent database connection


=head1 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 !


=head1 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 C<ping()> method of the DBI-module. This method returns true by default.
Most DBI drivers have a working C<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 C<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;