NAME

Gantry::Utils::DBConnHelper - connection info and dbh cache manager base module

SYNOPSIS

package Gantry::Utils::DBConnHelper::YourHelper;

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

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

sub get_dbh            {...}
sub set_dbh            {...}
sub get_conn_info      {...}
sub set_conn_info      {...}  # only for some helpers
sub get_auth_dbh       {...}
sub set_auth_dbh       {...}
sub get_auth_conn_info {...}
sub set_auth_conn_info {...}  # only for some helpers

DESCRIPTION

This is mostly a documentation module. You should probably use one of the available implementing modules like Gantry::Utils::DBConnHelper::Script, Gantry::Utils::DBConnHelper::MP13, etc. If none of those fit your needs you need to subclass this modules and define all of the methods listed below (see the synopsis for an example). If you choose to subclass, you will inherit the import method from this module. It allows your callers to pass a hash reference of database connection info in their use statement, instead of calling set_conn_info. This only works for the Script helper.

Required METHODS

Your module needs to implement the methods below. Failure to implement them will likely result in a fatal error at run time (or difficult to track bugs).

Get methods don't receive any parameters other than the invocant.

get_dbh

(required by Gantry::Utils::CDBI and Gantry::Utils::Model)

Return a valid dbh if you have one or undef if not.

set_dbh

(required by Gantry::Utils::CDBI and Gantry::Utils::Model)

Receives a dbh which it should store in its cache.

get_conn_info

(required by Gantry::Utils::CDBI and Gantry::Utils::Model)

Returns a hash reference of connection info with these keys:

dbconn

a full dsn suitable for passing directly to DBI's connect method

dbuser

the name of the database user

dbpass

the password for dbuser

Other keys in the hash are ignored.

Optional METHODS (Required for Gantry authentication)

In addition to connecting to an application database, Gantry can provide authentication. In that case it uses a separate connection to the app's auth database. This enables it to share authentication databases across apps.

Note that there is nothing that prevents you from storing the auth info in the same database as the app data. We just use two connections to add the flexibility to split these. In any case, if you are using Gantry auth, you must use the methods below.

(Note the symmetry between these methods and the ones above. These simply have auth_ inserted into their names.)

get_auth_dbh

(required by Gantry::Utils::AuthCDBI and Gantry::Utils::AuthModel)

Returns the database handle for the authentication database.

set_auth_dbh

(required by Gantry::Utils::AuthCDBI and Gantry::Utils::AuthModel)

Receives a database handle for the authentication database which it should cache for later retrieval by get_auth_dbh.

get_auth_conn_info

(required by Gantry::Utils::AuthCDBI and Gantry::Utils::AuthModel)

Returns a hash reference of connection info with these keys:

auth_dbconn

a full dsn suitable for passing directly to DBI's connect method

auth_dbuser

the name of the database user

auth_dbpass

the password for dbuser

Other keys in the hash are ignored.

It is perfectly reasonable to use the same database -- or even database handle -- for both the auth and regular connections. But, you need to provide the methods above so that Gantry can find them.

A METHOD for SUBCLASSES

This module does supply a useful import method which you can inherit. It allows users to supply the connection information hash as a parameter in their use statement like this:

use Gantry::Utils::DBConnHelper::YourSubclass {
    dbconn = 'dbi:Pg:dbname=mydb;host=127.0.0.1',
    dbuser = 'someuser',
    dbpass = 'not_saying',
};

The caller has the option of doing this in two steps (in case they need to calculate the connection information at run time):

use Gantry::Utils::DBConnHelper::YourSubclass;

# ... figure out what information to provide

Gantry::Utils::DBConnHelper::YourSubclass->set_conn_info(
    {
        dbconn = $dsn,
        dbuser = $user,
        dbpass = $pass,
    }
);

The import method does not help with authentication connection info.

OTHER METHODS

Gantry::Util::DBConnHelper::Script has two other methods for use by scripts, constructors, init methods or the like.

set_conn_info

Not implemented by mod_perl helpers.

Receives a hash of connection information suitable for use as the return value of get_conn_info.

set_auth_conn_info

Not implemented by mod_perl helpers.

Receives a hash reference of connection info which it should store for later retrieval via get_conn_info.

AUTHOR

Phil Crow <philcrow2000@yahoo.com>

COPYRIGHT and LICENSE

Copyright (c) 2005-6, Phil Crow.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.