Scripts

Where the information comes from matters not to the gantry. Once you know where your information will come from, you have two options for passing it to the model.

If the information is known at compile time (i.e. it is hard coded), you may simply say:

    use Gantry::Utils::DBConnHelper::Script {
        dbconn => 'dbi:Pg:dbname=some_db;host=127.0.0.1',
        dbuser => 'someone',
        dbpass => 'super_secret',
    };

Note that the dbconn key must have the full dsn needed by the DBI's connect method. This is true for all environments.

If you must calculate the information do the above in two steps:

    use Gantry::Utils::DBConnHelper::Script;

    # pull in your information from command line or conf file

    Gantry::Utils::DBConnHelper::Script->set_db_conn_info(
        {
            dbconn => $dsn,
            dbuser => $dbuser,
            dbpass => $dbpass,
        }
    );

Note that in both cases you should pass a hash reference.

If you need to access models which inherit from Gantry::Utils::AuthCDBI (or one of its authentications cousins), you need to also call set_auth_db_conn_info on Gantry::Utils::DBConnHelper::Script. That call is the same as the one for set_db_conn_info, except that the hash keys are auth_dbconn, auth_dbuser, and auth_dbpass.

mod_perl

    <Location />
        PerlSetVar dbconn dbi:Pg:dbname=some_db;host=127.0.0.1
        PerlSetVar dbuser someone
        PerlSetVar dbpass super_secret

        PerlSetVar auth_dbconn dbi:Pg:dbname=auth_db;host=127.0.0.1
        PerlSetVar auth_dbuser auth_user
        PerlSetVar auth_dbpass double_super_secret
    </Location>

CGI

Gantry also helps CGI scripts. Simply include the dbconn, dbuser, and dbpass keys (and their auth counterparts, if needed) in the config section of the hash you pass to Gantry::Engine::CGI->new:

    my $cgi = Gantry::Engine::CGI->new( {
        locations => {
            '/' => 'App::Base',
            # ...
        },
        config => {
            # ...
            dbconn => 'dbi:Pg:dbname=some_db;host=127.0.0.1',
            dbuser => 'someone',
            dbpass => 'super_secret',
        }

Gantry::Util::DBConnHelper

Subclasses of Gantry::Util::DBConnHelper

    package Gantry::Utils::DBConnHelper::Script;
    use strict; use warnings;

    use base 'Gantry::Utils::DBConnHelper';

    Gantry::Utils::DBConnHelper->set_subclass(
        'Gantry::Utils::DBConnHelper::Script'
    );

    my $dbh;
    my $conn_info;

    sub get_dbh {
        return $dbh;
    }

    sub set_dbh {
        my $class = shift;
        $dbh      = shift;
    }

    sub get_conn_info {
        return $conn_info;
    }

    sub set_conn_info {
        my $class  = shift;
        $conn_info = shift;
    }

    1;

At the top of the script we see that the module's full name is Gantry::Utils::DBConnHelper::Script and that it inherits from Gantry::Utils::DBConnHelper.

The first thing it should do is register with the base class. There can only be one connection helper in a given environment, so it calls the class method set_subclass with its own name. Now the base module will tell db_Main that this is the subclass with the info and cache.

The remainder of the script implements the simplest possible scheme for storing connection information and cached database handles.

Remember that scripts call set_conn_info directly (Gantry::Engine::CGI does this in its constructor) or supply the info in a hash reference parameter to use. The other methods are called by db_Main as needed.

The other helpers work similarly with two differences. Obviously, they use different caching schemes (mod_perl helpers use pnotes). But, set_conn_info is also handled differently. Here's where they are:

    engine type   where set_conn_info is called
    -----------------------------------------------------------
    scripts       manually before database work begins
    CGI           Gantry::Engine::CGI->new
    mod_perl      not called, params are fished from dir_config
                  on every request

So, the Gantry::Utils::DBConnHelper subclasses for mod_perl engines fish their connection information directly from the set vars in their get_conn_info methods.