.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "RoPkg::DB 3pm"
.TH RoPkg::DB 3pm "2021-12-26" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
RoPkg::DB \- A Singleton database pool class
.SH "VERSION"
.IX Header "VERSION"
0.1.12
.SH "DESCRIPTION"
.IX Header "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.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use RoPkg::DB;
\& 
\& sub main {
\&   my $dbp = new RoPkg::DB();
\& 
\&   eval {
\&     $dbp\->Add(\*(Aqdbi:mysql:database=mysql;host=localhost\*(Aq,
\&               \*(Aqroot\*(Aq,
\&               \*(Aq\*(Aq,
\&               \*(Aqlocal\*(Aq);
\&     $dbp\->Add(\*(Aqdbi:mysql:database=somedb;host=somehost\*(Aq,
\&               \*(Aqusername\*(Aq,
\&               \*(Aqmypass\*(Aq,
\&               \*(Aqsomedb\*(Aq);
\&   };
\& 
\&   die($@\->package . \*(Aq said: \*(Aq . $@\->message) if ref($@);
\& 
\&   print \*(AqConn to localhost is:\*(Aq,$dbp\->db_local,$/,
\&         \*(AqConn to remote is:\*(Aq,$dbp\->db_somedb,$/;
\&  
\&   $dbp\->Del(\*(Aqsomedb\*(Aq);
\& 
\& }
.Ve
.SH "SUBROUTINES/METHODS"
.IX Header "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.
.SS "\fBnew()\fP"
.IX Subsection "new()"
new is the contructor of the class. It does not do anything.
.ie n .SS "Add($dsn, $dbuser, $dbpass, $conn_name)"
.el .SS "Add($dsn, \f(CW$dbuser\fP, \f(CW$dbpass\fP, \f(CW$conn_name\fP)"
.IX Subsection "Add($dsn, $dbuser, $dbpass, $conn_name)"
add and initialize a new connection to the pool. \f(CW$dsn\fR must
be in the \s-1DBI\s0 format. \f(CW$dsn\fR and \f(CW$dbpass\fR are the username
and password used to connect to the database. \f(CW$conn_name\fR
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 \*(L"db_\*(R" .
.PP
Example:
.PP
.Vb 1
\& $dbp\->Add(\*(Aqdbi:mysql:database=mysql;host=localhost\*(Aq,\*(Aqroot\*(Aq,q{},\*(Aqlocal\*(Aq);
.Ve
.PP
The method that will be used to get the database handle for this connection
is db_local .
.PP
\&\fBAdd()\fR may raise the following exceptions:
.IP "*) Param::Missing" 3
.IX Item "*) Param::Missing"
.PD 0
.IP "*) DB::ConnExists" 3
.IX Item "*) DB::ConnExists"
.IP "*) DB::Connect" 3
.IX Item "*) DB::Connect"
.PD
.PP
\&\fIParam::Missing\fR is raised when \f(CW$dsn\fR, \f(CW$dbuser\fR or \f(CW$conn_name\fR 
are not defined. \fIDB::ConnExists\fR is raised when a connection
with the name \f(CW$conn_name\fR already exists. \fIDB::Connect\fR
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, \s-1DBI\s0 will raise a \fI\s-1DB\s0\fR exception. The
method always returns 1.
.SS "Del($name)"
.IX Subsection "Del($name)"
removes the connection named \f(CW$name\fR from the pool. The
connection is closed first in a civilised manner. If the
connection \f(CW$name\fR is not found, DB::ConnNotFound is raised.
.SS "Has($name)"
.IX Subsection "Has($name)"
Returns 0 if the connection named \f(CW$name\fR does not exists,
1 otherwise. Param::Missing exception is raised if
\&\f(CW$name\fR is not defined.
.SS "Reconnect($name)"
.IX Subsection "Reconnect($name)"
Force a reconnect of the connection named \f(CW$name\fR. If \f(CW$name\fR
is not defined, Param::Missing is raised. If a connection
named \f(CW$name\fR does not exists, DB::ConnNotFound is raised.
This method always returns 1.
.ie n .SS "TableExists($name, $table_name)"
.el .SS "TableExists($name, \f(CW$table_name\fP)"
.IX Subsection "TableExists($name, $table_name)"
Returns 1 if the table \f(CW$table_name\fR exists in the database
specified by the connection named \f(CW$name\fR, 0 otherwise. If
\&\f(CW$name\fR or \f(CW$table_name\fR parameters are not defined, a
Param::Missing exception is raised. If the connection
\&\f(CW$name\fR does not exists, DB::ConnNotFound is raised.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
RoPkg::DB requires perl 5.008 or later and the following modules:
.IP "RoPkg >= 0.4.4" 4
.IX Item "RoPkg >= 0.4.4"
.PD 0
.IP "\s-1DBI\s0" 4
.IX Item "DBI"
.IP "Class::Singleton" 4
.IX Item "Class::Singleton"
.IP "English" 4
.IX Item "English"
.PD
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
This module comes with tests. To run the tests, unpack the source
and run 'make test'
.SH "PERL CRITIC"
.IX Header "PERL CRITIC"
This module is perl critic level 2 compliant (with 1 exception)
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "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.
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
None known to the author
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
None known to the author
.SH "SEE ALSO"
.IX Header "SEE ALSO"
RoPkg::DBObject RoPkg::Exceptions RoPkg::Utils
.SH "AUTHOR"
.IX Header "AUTHOR"
Subredu Manuel <diablo@iasi.roedu.net>
.SH "LICENSE AND COPYRIGHT"
.IX Header "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 \s-1LICENSE\s0 file contains the full text of the license.