The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Konstrukt-0.5-beta13
River stage zero No dependents
++
/ Konstrukt::DBI

NAME

Konstrukt::DBI - Database handle pool

SYNOPSIS

        #receive connection
        my $db_source = 'DBI:'.$db_type.':'.$db_base.':'.$db_host;
        my $dbh = $Konstrukt::DBI->get_connection($db_source, $db_user, $db_pass) or return undef;
        
        #receive connection with default settings
        my $dbh = $Konstrukt::DBI->get_connection() or return undef;
        
        #do some query
        $dbh->do_stuff("SELECT foo FROM bar WHERE baz = 23");

DESCRIPTION

This module provides a database handle pool for the current process. If your plugin or website needs database connection it usually has to create one via DBI.

This can lead into several DBI connections per process, if there is more than one plugin used within this process. Each connection will consume resources and connection time.

So it will be a good idea to create a connection with the same parameters only once per process and share it over all plugins that need the connection.

This is what this module does: Provide a pool for DBI connections.

Your plugin only has to ask for a DB handle with the appropriate parameters. This module will create a connection, if there is no cached connection. Otherwise it will just pass the already existing handle. It will return undef and bail out an error message, if the connection failed.

Take a look at the "SYNOPSIS" for the usage of this module.

Additionally, this module will register a error handler, which will catch the errors that may occur during the database queries. The errors will be logged and put out on the website, if you use the error plugin on your website.

Note: A further performance advantage may be achieved by using the module Apache::DBI, which not only caches the handles within a single request but also over multiple requests.

CONFIGURATION

In the konstrukt.settings file:

        #this module may be disabled. it is enabled by default
        #dbi/use    0
        
        #default settings that will be used as defaults, if the specified settings are incomplete
        dbi/source dbi:mysql:database:host
        dbi/user   user
        dbi/pass   pass

As this will be the default settings for connection without an explicit definition of the connection settings, all modules/plugin which use this module will use these settings as default connection settings.

METHODS

new

Constructor of this class

init

Initialization of this class

get_connection

Creates a new DBI Connection if none has been created yet. Returns the database handle or undef on error.

Parameters:

  • $db_source - Database source in DBI-format

  • $db_user - User

  • $db_pass - Pass

error_handler

Handles an error event. Will generate an error message.

Parameters:

  • $message - The DBI error message

  • $dbh - The DB handle, within that the error occured

  • $rv - First value being returned by the method that failed (typically undef)

disconnect

Disconnects all cached connections

AUTHOR

Copyright 2006 Thomas Wittek (mail at gedankenkonstrukt dot de). All rights reserved.

This document is free software. It is distributed under the same terms as Perl itself.

SEE ALSO

Konstrukt