view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    These environment variables are used:

    MYSQL1, MYSQL2
        the 2 database names

    MYSQL_HOST
        the database host. If omitted "localhost" is used.

    MYSQL_USER, MYSQL_PASSWD
        you credentials.

    My "make test" command looks like:

     MYSQL1=dbitest1 MYSQL2=dbitest2 make test

   BerkeleyDB
    If "BerkeleyDB" is not available a few tests are skipped.

DEPENDENCIES
    BerkeleyDB is used if installed to make DBI handle statistics visible
    for the whole Apache process group instead of a single process.

    DBI 1.37

    perl 5.8.0

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

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

  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 *mysql* plugin.

    The plugin even recognizes connections to different databases on the
    same mysql server as the same connection and issues a "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.

  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 "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
    not cached at all. Here Apache::DBI::Cache differs from Apache::DBI.

    Later either "disconnect" is called on the handle or it simply goes out
    of scope and the garbage collector calls a "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. "$dbh->{Active}" will
    always return true no matter how often "disconnect" is called. Further,
    you can prevent a handle from getting reused by simply not forgetting
    it.

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

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

    Thereafter, "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.

  FUNCTIONS
    import - "use" parameter
        Parameters to the "use" statement are given in a "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,
                                ...;

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

        * use_bdb, bdb_env and bdb_memcache
          Apache::DBI::Cache can use BerleleyDB as a shared memory
          implementation to maintain statistics for a group of processes
          instead of a single process.

          "use_bdb" specify whether to use BerkeleyDB or not. If ommitted
          Apache::DBI::Cache will try to load and use BerkeleyDB. If that
          fails it silently provides per process statistics. If "use_bdb" is