NAME

DBI::Gofer::Transport::mod_perl - http mod_perl server-side transport for DBD::Gofer

SYNOPSIS

In httpd.conf:

    <Location /gofer>
        SetHandler perl-script 
        PerlHandler DBI::Gofer::Transport::mod_perl
    </Location>

For a corresponding client-side transport see DBD::Gofer::Transport::http.

DESCRIPTION

This module implements a DBD::Gofer server-side http transport for mod_perl. After configuring this into your httpd.conf, users will be able to use the DBI to connect to databases via your apache httpd.

CONFIGURATION

Gofer Configuration

Rather than provide a DBI proxy that will connect to any database as any user, you may well want to restrict access to just one or a few databases.

Or perhaps you want the database passwords to be stored only in httpd.conf so you don't have to maintain them in all your clients. In this case you'd probably want to use standard https security and authentication.

These kinds of configurations are supported by DBI::Gofer::Transport::mod_perl.

The most simple configuration looks like:

    <Location /gofer>
        SetHandler perl-script
        PerlHandler DBI::Gofer::Transport::mod_perl
    </Location>

That's equivalent to:

    <Perl>
        DBI::Gofer::Transport::mod_perl->add_configurations({
            default => {
                # ...DBI::Gofer::Transport::mod_perl configuration here...
            },
        });
    </Perl>

    <Location /gofer/example>
        SetHandler perl-script
        PerlSetVar GoferConfig default
        PerlHandler DBI::Gofer::Transport::mod_perl
    </Location>

Refer to DBI::Gofer::Transport::mod_perl documentation for details of the available configuration items, their behaviour, and their default values.

The DBI::Gofer::Transport::mod_perl->add_configurations({...}) call defines named configurations. The PerlSetVar GoferConfig clause specifies the configuration to be used for that location.

A single location can specify multiple configurations using PerlAddVar:

        PerlSetVar GoferConfig default
        PerlAddVar GoferConfig example_foo
        PerlAddVar GoferConfig example_bar

in which case the added configurations are merged into the current configuration for that location. Conflicting entries in later configurations override those in earlier ones (for hash references the contents of the hashes are merged). In this way a small number of configurations can be mix-n-matched to create specific configurations for specific location urls.

A typical usage might be to define named configurations for each specific database being used and then define a coresponding location for each of those. That would also allow standard http location access controls to be used (though at the moment the http transport doesn't support http authentication).

That approach can also provide a level of indirection by avoiding the need for the clients to know and use the actual DSN. The clients can just connect to the specific gofer url with an empty DSN. This means you can change the DSN being used without having to update the clients.

Apache Configuration

KeepAlive

The gofer http transport will use HTTP/1.1 persistent connections if possible. You may want to tune the server-side settings KeepAlive, keepAliveTimeout, and MaxKeepAliveRequests.

Apache::Status

DBI::Gofer::Transport::mod_perl installs an extra "DBI Gofer" menu item into the Apache::Status menu, so long as the Apache::Status module is loaded first.

This is very useful.

Clicking on the DBI Gofer menu items leads to a page showing the configuration and statistics for the Gofer executor object associated with each Location using the DBI::Gofer::Transport::mod_perl handler in the httpd.conf file.

Gofer executor objects are created and cached on first use so when the httpd is (re)started there won't be any details to show.

Each Gofer executor object shown includes a link that will display more detail of that particular Gofer executor. Currently the only extra detail shown is a listing showing recent requests and responses followed by a summary. There's a lot of useful information here. The number of recent recent requests and responses shown is controlled by the track_recent configuration value.

BUGS AND LIMITATIONS

Please report any bugs or feature requests to bug-dbi-gofer-transport-mod_perl@rt.cpan.org, or through the web interface at http://rt.cpan.org.

METHODS

add_configurations

  DBI::Gofer::Transport::mod_perl->add_configurations( \%hash_of_hashes );

Takes a reference to a hash containing gofer configuration names and their corresponding configuration details.

These are added to a cache of gofer configurations. Any existing configurations with the same names are replaced.

A warning will be generated for each configuration that contains any invalid keys.

executor_for_apache_request

  $executor = $self->executor_for_apache_request( $r );

Takes an Apache request object and returns a DBI::Gofer::Execute object with the appropriate configuration for the url of the request.

The executors are cached so a new DBI::Gofer::Execute object will be created only for the first gofer request at a specific url. Subsequent requests get the cached executor.

handler

This is the method invoked by Apache mod_perl to handle the request.

TO DO

Add way to reset the stats via the Apache::Status ui.

Move generic executor config code into DBI::Gofer::Executor::Config or somesuch so other transports can use it.

AUTHOR

Tim Bunce, http://www.linkedin.com/in/timbunce

LICENCE AND COPYRIGHT

Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

SEE ALSO

DBD::Gofer and DBD::Gofer::Transport::http.