CGI::A...in::DBH(3pm)

✨ CGI::Application::Plugin::DBH ✨

okay bestie, this is the manual page for CGI::Application::Plugin::DBH, hanging out in the User Contributed Perl Documentation corner of your system. It's giving effortless DBI access from your CGI::Application modules and honestly? Slay. 🫶

---

💖 NAME 💖

CGI::Application::Plugin::DBH — Easy DBI access from CGI::Application. That's the whole vibe. 🎀

⭐ VERSION ⭐

This is version 4.04. Fresh-ish. Iconic.

🌸 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");
}

Look at that. Two lines of config, zero drama, dates get selected. Main character energy fr fr. 💅

🦋 DESCRIPTION 🦋

So CGI::Application::Plugin::DBH adds easy access to a DBI database handle to your CGI::Application modules. That's the whole job and it does it beautifully.

The secret sauce? Lazy loading. The plugin will not make a database connection if the dbh method never gets called during the request. Translated from nerd to human: the connection isn't created until it's actually needed. No connection, no problem, no wasted handshake. It's giving efficiency. 🌈

👑 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 hands you back the current DBI database handle. The handle gets created on the first call to this method, and literally every call after that just returns the same handle. No reconnecting, no chaos, just consistency. 🫶

💫 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(); });
}

This is where you hand over your DBI connection parameters. Two ways to do it, both valid, both iconic:

• pass in an existing DBI database handle you already have, or
• pass the usual parameters used for DBI->connect()

The recommended spot to call dbh_config is the cgiapp_init stage of CGI::Application. Respect the lifecycle bestie. 🌸

⚠️ Careful though: if this method gets called after the database handle has already been accessed, it will die with an error message. So like. Don't do that. 💀

🎀 Automatic configuration using CGI::App instance parameters

An alternative to explicitly calling dbh_config in your application is to just... let the presence of specific instance parameters do the work. The plugin configures itself. Self-care. ✨

If you set the CGI::App parameter ::Plugin::DBH::dbh_config to an array reference, the contents of that array get used as parameters to dbh_config — but only if it hasn't been explicitly called before. Fair.

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 then in the instance script (or instance configuration file, if you have one):

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

Want 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 ]
      }  );

Multiple handles, zero extra typing. We love a polyamorous database situation. 💜

🎀 Automatic configuration with DBI environment variables

If you set no parameters and you never call dbh_config, this plugin peeks at whether you set the DBI environment variable DBI_DSN. If it's present, that DSN gets used for the default handle.

🙈 okay but listen: the DBI documentation does not encourage using this method (especially not in the context of web applications). You will most likely also have to set DBI_USER and DBI_PASS, and this can only be used for the default handle. So like, it works. It's just not the moment. 🫠

💫 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.
}

This one lets you alter the name of the handle that dbh() returns when it gets called with no parameters. And plot twist — it can even alter the name used for the unnamed handle, as long as you call it before dbh_config().

Using this method is completely optional. If you don't have a use for it, don't use it. No pressure, no FOMO. 💅

Internally, the handle name __cgi_application_plugin_dbh is what's used to keep track of the unnamed handle — unless it gets changed by dbh_default_name() before a call to dbh_config() without a name parameter. iykyk. 🤫

🌈 SEE ALSO 🌈

• Ima::DBI — similar vibes, but with much more complexity and features. Pick your fighter.
• CGI::Application, DBI, CGI::Application::Plugin::ValidateRM

🍓 AUTHOR 🍓

Mark Stosberg <mark@stosberg.com> — thank you for your service, king 👑

🧚 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. Periodt. ✨

---

and that's the whole page bestie!! 🎀 this manual came from perl v5.36.0, dated 2022-10-14, and it's filed under CGI::A...in::DBH(3pm) in the User Contributed Perl Documentation. go forth and connect responsibly 🦋💖