view release on metacpan or  search on metacpan

lib/Apache2/Translation/DB.pod  view on Meta::CPAN

=head1 NAME

Apache2::Translation::DB - A provider for Apache2::Translation

=head1 SYNOPSIS

  <TranslationProvider DB>
      Database  dbi:mysql:dbname:host
      User      username
      Password  password
      Singleton 1
      Table     tablename
      Key       keycolumn
      Uri       uricolumn
      Block     blockcolumn
      Order     ordercolumn
      Action    actioncolumn
      Cachetbl  cachetablename
      Cachecol  cachecolumn
      Cachesize 1000
  </TranslationProvider>

  or

  $provider=Apache2::Translation::DB->new(Database=>..., ...);

  $provider->start;
  $provider->stop;

=head1 DESCRIPTION

The C<DB> provider implements the C<Apache2::Translation> provider interface
as documented in L<Apache2::Translation::_base>. It provides for all optional
functions. No additional functions are supported.

=head2 B<Parameters>

=over 2

=item B<database DSN>

a string describing a L<DBI> database

=item B<user NAME>

=item B<password PW>

the user and password to use

=item B<table NAME>

names the translation table.

=item B<key NAME>

=item B<uri NAME>

=item B<block NAME>

=item B<order NAME>

=item B<action NAME>

=item B<id NAME>

=item B<notes NAME>

name the columns of the translation table to use. The C<id> and C<notes>
columns are necessary only in combination with the admin interface.
The C<id> column if specified must have a default value on C<INSERT>
generating unique keys, something like C<autoincrement> in MySQL or
C<nextval('sequence')> in PostgreSQL.

=item B<cachetbl NAME>

=item B<cachecol NAME>

name the cache table and its column

=item B<cachesize NUMBER|infinite>

sets the maximum number of cached block lists, default is 1000.

If set to C<infinite> the cache has no limits.

A L<Tie::Cache::LRU> cache is used.

C<Apache2::Translation::DB> caches database entries as lists of blocks.
Each list of blocks consumes one cache entry.

For each request first the following lookup is done:

 SELECT MAX($cachecol) FROM $cachetbl

The resulting value is then compared with the previous read value. If it
has changed, it means the cache is invalid. If not, the cache is valid
and if all information is found in the cache, no further database lookups
are needed.

=item B<singleton BOOLEAN>

Normally, C<Apache2::Translation> tries to connect to the database at
server startup. Then it inspects the database handle to see if
C<Apache::DBI> or C<Apache::DBI::Cache> are loaded. If so, it will
connect and disconnect for each translation phase / request, thus,
put back the connection to the connection pool.

If neither of them is loaded the DB connection is used as a singleton.