.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CGI::Application::Plugin::DBH 3pm"
.TH CGI::Application::Plugin::DBH 3pm "2013-11-24" "perl v5.18.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"
CGI::Application::Plugin::DBH \- Easy DBI access from CGI::Application
.SH "VERSION"
.IX Header "VERSION"
version 4.04
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use CGI::Application::Plugin::DBH (qw/dbh_config dbh/);
\&
\& sub cgiapp_init  {
\&    my $self = shift;
\&
\&    # use the same args as DBI\->connect();
\&    $self\->dbh_config($data_source, $username, $auth, \e%attr);
\&
\&    # or to use more than one dbh
\&    $self\->dbh_config(\*(Aqmy_handle\*(Aq,
\&            [ $data_source, $user, $auth, \e%attr ]);
\&    $self\->dbh_config(\*(Aqmy_other_handle\*(Aq,
\&            [ $data_source, $user, $auth, \e%attr ]);
\& }
\&
\& sub my_run_mode {
\&    my $self = shift;
\&
\&    my $date = $self\->dbh\->selectrow_array("SELECT CURRENT_DATE");
\&    # again with a named handle
\&    $date = $self\->dbh(\*(Aqmy_handle\*(Aq)\->selectrow_array("SELECT CURRENT_DATE");
\&
\&    # OR ...
\&
\&    my $dbh = $self\->dbh;
\&    # again with a named handle
\&    $dbh = $self\->dbh(\*(Aqmy_other_handle\*(Aq);
\&    my $date = $dbh\->selectrow_array("SELECT CURRENT_DATE");
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
CGI::Application::Plugin::DBH adds easy access to a \s-1DBI\s0 database handle to
your CGI::Application modules.  Lazy loading is used to prevent a database
connection from being made if the \f(CW\*(C`dbh\*(C'\fR method is not called during the
request.  In other words, the database connection is not created until it is
actually needed.
.SH "METHODS"
.IX Header "METHODS"
.SS "\fIdbh()\fP"
.IX Subsection "dbh()"
.Vb 3
\& my $date = $self\->dbh\->selectrow_array("SELECT CURRENT_DATE");
\& # again with a named handle
\& $date = $self\->dbh(\*(Aqmy_handle\*(Aq)\->selectrow_array("SELECT CURRENT_DATE");
\&
\& # OR ...
\&
\& my $dbh = $self\->dbh;
\& # again with a named handle
\& $dbh = $self\->dbh(\*(Aqmy_other_handle\*(Aq);
\& my $date = $dbh\->selectrow_array("SELECT CURRENT_DATE");
.Ve
.PP
This method will return the current \s-1DBI\s0 database handle.  The database handle is created on
the first call to this method, and any subsequent calls will return the same handle.
.SS "\fIdbh_config()\fP"
.IX Subsection "dbh_config()"
.Vb 2
\& sub cgiapp_init  {
\&    my $self = shift;
\&
\&    # use the same args as DBI\->connect();
\&    $self\->dbh_config($data_source, $username, $auth, \e%attr);
\&
\&    # or to use more than one dbh
\&    $self\->dbh_config(\*(Aqmy_handle\*(Aq,
\&            [ $data_source, $user, $auth, \e%attr ]);
\&    $self\->dbh_config(\*(Aqmy_other_handle\*(Aq,
\&            [ $data_source, $user, $auth, \e%attr ]);
\&
\&    # ...or use some existing handle you have
\&    $self\->dbh_config($DBH);
\&    $self\->dbh_config(\*(Aqmy_handle\*(Aq, $DBH);   # this works too
\&
\&    # Use a callback to create your owh handle that is still lazy loaded
\&    $self\->dbh_config(sub { DBI\->connect_cached(); });
\& }
.Ve
.PP
Used to provide your \s-1DBI\s0 connection parameters. You can either pass in an existing
\&\s-1DBI\s0 database handle, or provide the usual parameters used for \s-1DBI\-\s0>\fIconnect()\fR.
.PP
The recommended place to call \f(CW\*(C`dbh_config\*(C'\fR is in the \f(CW\*(C`cgiapp_init\*(C'\fR
stage of CGI::Application.  If this method is called after the database handle
has already been accessed, then it will die with an error message.
.PP
\fIAutomatic configuration using CGI::App instance parameters\fR
.IX Subsection "Automatic configuration using CGI::App instance parameters"
.PP
An alternative to explicitly calling \f(CW\*(C`dbh_config\*(C'\fR in your application
is to rely on the presence of specific instance parameters that allow the
plugin to configure itself.
.PP
If you set the CGI::App parameter \f(CW\*(C`::Plugin::DBH::dbh_config\*(C'\fR to
an array reference the contents of that array will be used as parameters to
\&\f(CW\*(C`dbh_config\*(C'\fR (if it has not been explicitly called before).
.PP
The code in the synopsis can be rewritten as
.PP
.Vb 2
\&  use CGI::Application::Plugin::DBH (qw/dbh/);
\&    # no longer a need to import dbh_config
\&
\&  sub cgiapp_init  {
\&     # you do not need to do anything here
\&  }
\&
\&  sub my_run_mode {
\&
\&    # this part stays unchanged
\&
\&    ....
\&
\&  }
.Ve
.PP
and in the instance script ( or instance configuration file, if you have)
.PP
.Vb 2
\&   $app\->param(\*(Aq::Plugin::DBH::dbh_config\*(Aq =>
\&        [ $data_source, $username, $auth, \e%attr ] );
.Ve
.PP
If you want to configure more than one handle, set up a hash with the handle names
as keys:
.PP
.Vb 4
\&    $app\->param(\*(Aq::Plugin::DBH::dbh_config\*(Aq =>
\&        { my_handle => [ $data_source, $username, $auth, \e%attr ] ,
\&          my_other_handle => [ $data_source, $username, $auth, \e%attr ]
\&        }  );
.Ve
.PP
\fIAutomatic configuration with \s-1DBI\s0 environment variables\fR
.IX Subsection "Automatic configuration with DBI environment variables"
.PP
If you do not set any parameters, and do not call \f(CW\*(C`dbh_config\*(C'\fR, this plugin
checks to see if you set the \s-1DBI\s0 environment variable \f(CW\*(C`DBI_DSN\*(C'\fR. If present,
this \s-1DSN\s0 will be used for the default handle. Note that the \s-1DBI\s0 documentation
does not encourage using this method (especially in the context of web applications),
that you will most likely have to also set \f(CW\*(C`DBI_USER\*(C'\fR and \f(CW\*(C`DBI_PASS\*(C'\fR, and
that this can only be used for the default handle.
.SS "\fIdbh_default_name()\fP"
.IX Subsection "dbh_default_name()"
.Vb 2
\& sub my_runmode {
\&    my $self = shift;
\&
\&    my $old_handle_name = $self\->dbh_default_name(\*(Aqmy_handle\*(Aq);
\&    $self\->some_legacy_code();  # some_legacy_code() will get "my_handle"
\&                                # when it calls $self\->dbh() without parameters
\&
\&    $self\->dbh_default_name($old_handle_name);    # Return to normal.
\& }
.Ve
.PP
Can be used to alter the name of the handle that is returned by \fIdbh()\fR when
called with no parameters. It can even be used to alter the name used for the
unnamed handle if called before \fIdbh_config()\fR.
.PP
Using this method is completely optional. If you don't have a use for it don't
use it. Internally the handle name \*(L"_\|_cgi_application_plugin_dbh\*(R" is used to
keep track of the unnamed handle unless it is changed by \fIdbh_default_name()\fR
before a call to \fIdbh_config()\fR without a name parameter.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Ima::DBI is similar, but has much more complexity and features.
.PP
CGI::Application, \s-1DBI\s0, CGI::Application::Plugin::ValidateRM
.SH "AUTHOR"
.IX Header "AUTHOR"
Mark Stosberg <mark@stosberg.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2013 by Mark Stosberg.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.