NAME

       RoPkg::DB - A Singleton database pool class

VERSION

       0.1.12

DESCRIPTION

       RoPkg::DB is a database pool class. Using this class you can have access to multiple
       databases (no matter what kind of database), from a single object. RoPkg::DB is ideal in
       persistent environments because at base, is a singleton class. This class is intensively
       used by Simba but it can be used in any other project.

SYNOPSIS

        use RoPkg::DB;

        sub main {
          my $dbp = new RoPkg::DB();

          eval {
            $dbp->Add('dbi:mysql:database=mysql;host=localhost',
                      'root',
                      '',
                      'local');
            $dbp->Add('dbi:mysql:database=somedb;host=somehost',
                      'username',
                      'mypass',
                      'somedb');
          };

          die($@->package . ' said: ' . $@->message) if ref($@);

          print 'Conn to localhost is:',$dbp->db_local,$/,
                'Conn to remote is:',$dbp->db_somedb,$/;

          $dbp->Del('somedb');

        }

SUBROUTINES/METHODS

       All methods (besides new), raise OutsideClass exception when are not called within a class
       instance. Also, each method may raise diferent exceptions from one case to another. Please
       read the documentation for each method to find out what are the exceptions raised by each
       method.

   new()
       new is the contructor of the class. It does not do anything.

   Add($dsn, $dbuser, $dbpass, $conn_name)
       add and initialize a new connection to the pool. $dsn must be in the DBI format. $dsn and
       $dbpass are the username and password used to connect to the database. $conn_name is the
       method who will be used to access the database handle.  Please note that the method that
       will be created will be prefixed with "db_" .

       Example:

        $dbp->Add('dbi:mysql:database=mysql;host=localhost','root',q{},'local');

       The method that will be used to get the database handle for this connection is db_local .

       Add() may raise the following exceptions:

       *) Param::Missing
       *) DB::ConnExists
       *) DB::Connect

       Param::Missing is raised when $dsn, $dbuser or $conn_name are not defined. DB::ConnExists
       is raised when a connection with the name $conn_name already exists. DB::Connect is raised
       when the connection with the database could not be established. Besides this exceptions,
       each database handler has RaiseError set to 1 and PrintError set to 0. Also, when errors
       occurs, DBI will raise a DB exception. The method always returns 1.

   Del($name)
       removes the connection named $name from the pool. The connection is closed first in a
       civilised manner. If the connection $name is not found, DB::ConnNotFound is raised.

   Has($name)
       Returns 0 if the connection named $name does not exists, 1 otherwise. Param::Missing
       exception is raised if $name is not defined.

   Reconnect($name)
       Force a reconnect of the connection named $name. If $name is not defined, Param::Missing
       is raised. If a connection named $name does not exists, DB::ConnNotFound is raised.  This
       method always returns 1.

   TableExists($name, $table_name)
       Returns 1 if the table $table_name exists in the database specified by the connection
       named $name, 0 otherwise. If $name or $table_name parameters are not defined, a
       Param::Missing exception is raised. If the connection $name does not exists,
       DB::ConnNotFound is raised.

DEPENDENCIES

       RoPkg::DB requires perl 5.008 or later and the following modules:

       RoPkg >= 0.4.4
       DBI
       Class::Singleton
       English

DIAGNOSTICS

       This module comes with tests. To run the tests, unpack the source and run 'make test'

PERL CRITIC

       This module is perl critic level 2 compliant (with 1 exception)

CONFIGURATION AND ENVIRONMENT

       This module does not use any configuration files or environment variables. The used
       modules however may use such things. Please refer to each module man page for more
       information.

INCOMPATIBILITIES

       None known to the author

BUGS AND LIMITATIONS

       None known to the author

SEE ALSO

       RoPkg::DBObject RoPkg::Exceptions RoPkg::Utils

AUTHOR

       Subredu Manuel <diablo@iasi.roedu.net>

LICENSE AND COPYRIGHT

       Copyright (C) 2005 Subredu Manuel.  All Rights Reserved.  This module is free software;
       you can redistribute it and/or modify it under the same terms as Perl itself.  The LICENSE
       file contains the full text of the license.