view release on metacpan or  search on metacpan

lib/Apache/DBI/Cache.pod  view on Meta::CPAN

=head1 NAME

Apache::DBI::Cache - a DBI connection cache

=head1 SYNOPSIS

  use Apache::DBI::Cache debug=>3, bdb_env=>'/tmp/tmp',
                         plugin=>'Apache::DBI::Cache::mysql',
                         plugin=>['DBM', sub {...}, sub {...}],
                         ...;

=head1 DESCRIPTION

This module is an alternative to the famous L<Apache::DBI> module. As
Apache::DBI it provides persistent DBI connections.

It can be used with mod_perl1, mod_perl2 and even standalone.

=head2 WHY ANOTHER MODULE FOR THE SAME?

Apache::DBI has a number of limitations. Firstly, it is not possible to
get multiple connections with the same parameters. A common scenario for
example is to use one connection to perform transactions and another to
perform simple lookups in the same database. With Apache::DBI it is very
likely to get the same connection if you mean to use different.

With Apache::DBI all connections are reset at end of a request.

Apache::DBI does not regard database specific functions to cache handles
more aggressively. For example a mysql DSN can look like

 dbi:mysql:test:localhost:3306

or

 dbi:mysql:host=localhost;db=test

Both point to the same database but for Apache::DBI they are different.
Apache::DBI::Cache recognizes these two by means of a I<mysql> plugin.

The plugin even recognizes connections to different databases on the
same mysql server as the same connection and issues a C<USE database>
command before returning the actual handle to the user. Hence, with
Apache::DBI::Cache many the overall number of connections to a DB server
can be dramatically reduced.

=head2 HOW DOES IT WORK?

To decide whether to use Apache::DBI::Cache or not it is essential to
know how it works. As with Apache::DBI Apache::DBI::Cache uses a hook
provided by the DBI module to intercept C<< DBI->connect() >> calls.
Also do Apache::DBI::Cache maintain a cache of active handles.

When a new connection is requested and the cache is empty a new connection
is established and returned to the user. At this point it is B<not> cached at
all. Here Apache::DBI::Cache differs from Apache::DBI.

Later either C<disconnect> is called on the handle or it simply
goes out of scope and the garbage collector calls a C<DESTROY> method
if provided. Both events are intercepted by Apache::DBI::Cache. Only then
the handle is put in the cache.

This means a handle is never really disconnected. C<< $dbh->{Active} >>
will always return true no matter how often C<disconnect> is called.
Further, you can prevent a handle from getting reused by simply not
forgetting it.

=head2 USAGE

Different to Apache::DBI Apache::DBI::Cache must be C<use>ed not C<require>ed.
That means it's C<import> function must be called.

When used with mod_perl (versions 1.x or 2.x) this is best done in a
C<startup.pl> or in a C<< <Perl> >> section in the C<httpd.conf>.
See mod_perl documentation for more information.

Thereafter, C<< DBI->connect >> is called as usual. No special treatment
is needed.

When Apache::Status or Apache2::Status is used Apache::DBI::Cache provides
an extra menu item to show statistics on handles. The loading
order of the Apache::Status and Apache::DBI::Cache is irrelevant.

=head2 FUNCTIONS

=over 4

=item B<import> - C<use> parameter

Parameters to the C<use> statement are given in a C<< key => value >> fashion.

 use Apache::DBI::Cache debug=>3, logger=>sub {...},
                        plugin=>['driver', sub {}, sub {}],
                        plugin=>'Apache::DBI::Cache::mysql',
                        use_bdb=>1,
                        bdb_env=>'/tmp/mybdbenv',
                        bdb_memcache=>20*1024,
                        ...;

=over 2

=item * B<plugin>

loads a plugin, see also L</"PLUGINS"> below. The plugin can be specified
as a 3-element array or by name. In the second case the C<import> simply
C<use>s the module. This option can be given multiple times.

=item * B<use_bdb>, B<bdb_env> and B<bdb_memcache>