NAME

       CGI::Application::Plugin::DBH - Easy DBI access from CGI::Application

VERSION

       version 4.04

SYNOPSIS

        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, \%attr);

           # or to use more than one dbh
           $self->dbh_config('my_handle',
                   [ $data_source, $user, $auth, \%attr ]);
           $self->dbh_config('my_other_handle',
                   [ $data_source, $user, $auth, \%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('my_handle')->selectrow_array("SELECT CURRENT_DATE");

           # OR ...

           my $dbh = $self->dbh;
           # again with a named handle
           $dbh = $self->dbh('my_other_handle');
           my $date = $dbh->selectrow_array("SELECT CURRENT_DATE");
        }

DESCRIPTION

       CGI::Application::Plugin::DBH adds easy access to a DBI database handle to your
       CGI::Application modules.  Lazy loading is used to prevent a database connection from
       being made if the "dbh" method is not called during the request.  In other words, the
       database connection is not created until it is actually needed.

METHODS

   dbh()
        my $date = $self->dbh->selectrow_array("SELECT CURRENT_DATE");
        # again with a named handle
        $date = $self->dbh('my_handle')->selectrow_array("SELECT CURRENT_DATE");

        # OR ...

        my $dbh = $self->dbh;
        # again with a named handle
        $dbh = $self->dbh('my_other_handle');
        my $date = $dbh->selectrow_array("SELECT CURRENT_DATE");

       This method will return the current DBI database handle.  The database handle is created
       on the first call to this method, and any subsequent calls will return the same handle.

   dbh_config()
        sub cgiapp_init  {
           my $self = shift;

           # use the same args as DBI->connect();
           $self->dbh_config($data_source, $username, $auth, \%attr);

           # or to use more than one dbh
           $self->dbh_config('my_handle',
                   [ $data_source, $user, $auth, \%attr ]);
           $self->dbh_config('my_other_handle',
                   [ $data_source, $user, $auth, \%attr ]);

           # ...or use some existing handle you have
           $self->dbh_config($DBH);
           $self->dbh_config('my_handle', $DBH);   # this works too

           # Use a callback to create your owh handle that is still lazy loaded
           $self->dbh_config(sub { DBI->connect_cached(); });
        }

       Used to provide your DBI connection parameters. You can either pass in an existing DBI
       database handle, or provide the usual parameters used for DBI->connect().

       The recommended place to call "dbh_config" is in the "cgiapp_init" 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.

       Automatic configuration using CGI::App instance parameters

       An alternative to explicitly calling "dbh_config" in your application is to rely on the
       presence of specific instance parameters that allow the plugin to configure itself.

       If you set the CGI::App parameter "::Plugin::DBH::dbh_config" to an array reference the
       contents of that array will be used as parameters to "dbh_config" (if it has not been
       explicitly called before).

       The code in the synopsis can be rewritten as

         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

           ....

         }

       and in the instance script ( or instance configuration file, if you have)

          $app->param('::Plugin::DBH::dbh_config' =>
               [ $data_source, $username, $auth, \%attr ] );

       If you want to configure more than one handle, set up a hash with the handle names as
       keys:

           $app->param('::Plugin::DBH::dbh_config' =>
               { my_handle => [ $data_source, $username, $auth, \%attr ] ,
                 my_other_handle => [ $data_source, $username, $auth, \%attr ]
               }  );

       Automatic configuration with DBI environment variables

       If you do not set any parameters, and do not call "dbh_config", this plugin checks to see
       if you set the DBI environment variable "DBI_DSN". If present, this DSN will be used for
       the default handle. Note that the DBI documentation does not encourage using this method
       (especially in the context of web applications), that you will most likely have to also
       set "DBI_USER" and "DBI_PASS", and that this can only be used for the default handle.

   dbh_default_name()
        sub my_runmode {
           my $self = shift;

           my $old_handle_name = $self->dbh_default_name('my_handle');
           $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.
        }

       Can be used to alter the name of the handle that is returned by dbh() when called with no
       parameters. It can even be used to alter the name used for the unnamed handle if called
       before dbh_config().

       Using this method is completely optional. If you don't have a use for it don't use it.
       Internally the handle name "__cgi_application_plugin_dbh" is used to keep track of the
       unnamed handle unless it is changed by dbh_default_name() before a call to dbh_config()
       without a name parameter.

SEE ALSO

       Ima::DBI is similar, but has much more complexity and features.

       CGI::Application, DBI, CGI::Application::Plugin::ValidateRM

AUTHOR

       Mark Stosberg <mark@stosberg.com>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2013 by Mark Stosberg.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.