/ 
Config-DBI-1.8
River stage zero No dependents
/ Config::DBI

NAME

Config::DBI - database connection support via Config::ApacheFormat files

SYNOPSIS

In .cshrc:

setenv DBI_CONF dbi.conf

In dbi.conf:

# Pass may be a password, or <STDIN> in which case, the password is 
# is prompted for:

Pass	     <STDIN>

# Connect attribute

# dbi_connect_method is a standard part of DBI. Its casing does differ from
# all other attributes, but I did not create the DBI spec, I am simply
# following it:
# http://search.cpan.org/~timb/DBI-1.38/DBI.pm#DBI_Class_Methods

# Other options for this value are: connect_cached, Apache::DBI::connect

dbi_connect_method connect

# Attributes common to all handles and settable
# Listed in the order given in the DBI docs.
# http://search.cpan.org/~timb/DBI/DBI.pm#METHODS_COMMON_TO_ALL_HANDLES

Warn 1 
InactiveDestroy
PrintError 0 
PrintWarn 1
RaiseError 0 
HandleError  Exception::Class::DBI->handler
HandleSetErr sub { my ($handle, $err, $errstr, $state, $method) = @_; }
ShowErrorStatement 1
TraceLevel 0
FetchHashKeyName NAME_lc
ChopBlanks 0
LongReadLen 0
LongTruncOk 0
TaintIn 1 
TaintOut 0
# omit Taint (shortcut to set both TaintIn and TaintOut)
Profile 0

# Attributes for database handles
# http://search.cpan.org/~timb/DBI/DBI.pm#Database_Handle_Attributes 

AutoCommit 0
RowCacheSize 0

# Connection info

# Description of a database we would like to connect to

<DBI basic>
 DSN              dbi:Pg:dbname=mydb
 User             postgres
 AutoCommit  1
</DBI>

# Description of another database

<DBI basic_test>
 DSN   dbi:Pg:dbname=mydb_test
 User  test
 Pass  test
</DBI>

In Ye Olde Pure Perl Programme:

use Config::DBI;

my $dbh = Config::DBI->basic_test;

Or:

my %connect = Config::DBI->hash('basic_test');

DESCRIPTION

Config::DBI is a module based on 2 years of developing and using DBIx::Connect. For most usage, DBIx::Connect was fine. However two principal issues began to loom with continued usage. First, AppConfig is very hard to use and understand. So maintenance of the code was a real headache. Second, it was difficult to arrange an AppConfig file to create over-writable defaults. The concerns led to the following post:

http://perlmonks.org/index.pl?node_id=299749

A reply by Perrin led me to develop a completely new module based on Config::ApacheFormat.

This module's main purpose is to provide a way to get DBI database handles with very few lines of code. It does also have an API call to get the connection data so that you can do what you want with it. This is useful when one is using DBIx::AnyDBD, Alzabo or some other package which has different conventions for creating DBI dbhs.

INSTALLATION and USAGE

Create a DBI configuration file

A documented sample one, dbi.conf, comes with the distribution.

No directives are allowed in this file other than User, Pass, DSN, DBI and the names of the DBI attributes.

Create the DBI_CONF environmental variable in your .bashrc

Set this to the name of the configuration file that Config::DBI will be using.

export DBI_CONF=$HOME/dbi.conf

Source .bashrc

shell> source ~/.bashrc

Run scripts/try-connect.pl try it out:

   ~/hacks/config-dbi/scripts $ perl -I../lib try-connect.pl
Connection successful.
   ~/hacks/config-dbi/scripts $

Install it

perl Makefile.PL
make
make test
make install

METHODS

my $dbh = Config::DBI->$DBI_block

This method looks for a DBI block labeled $DBI_block and loads in the configuration information from that block as well as its parents. It then creates and returns a DBI database handle.

Should an error occur and HandleError is unbound, then $DBI::errstr is printed with a die. If HandleError is defined, then its called per the DBI spec.

my %hash = Config::DBI->hash($DBI_block);

This method returns a hash of DBI connection data. Here is a sample of what such data would look like from the config file in the "SYNOPSIS".

$VAR1 = {
        'DSN' => 'dbi:Pg:dbname=mydb',
        'User' => 'postgres',
        'Pass' => undef,
        'Attr' => {
                    'Profile' => '0',
                    'FetchHashKeyName' => '0',
                    'TraceLevel' => '0',
                    'HandleError' => sub { "DUMMY" },
                    'InactiveDestroy' => 1,
                    'AutoCommit' => '1',
                    'TaintOut' => '0',
                    'RaiseError' => '0',
                    'LongTruncOk' => '0',
                    'ChopBlanks' => '0',
                    'PrintError' => '0',
                    'dbi_connect_method' => 'connect',
                    'LongReadLen' => '0',
                    'Warn' => '1',
                    'ShowErrorStatement' => '1',
                    'TaintIn' => '1'
                  }
      };

EXPORT

None by default.

SEE ALSO

Most of the information for this section is a regurgitation of:

http://perlmonks.org/index.pl?node_id=292455

DBIx::Password

The very first module to abstract the process of DBI database connections. Repeated rejection of my patches to this module to support methods such as the hash() method of this package led to the creation of DBIx::Connect.

XML::Object::DBI

This module does connection and SQL warehousing via XML.

Ima::DBI

Ima:DBI is part of the tech stack Perl's most popular Perl database wrapper, Class::DBI. It does connection and SQL warehousing via Perl.

DBIx::Connect

The first module I wrote to address what I could not address under the auspices of DBIx::Password.

AUTHOR

Terrence Brannon, <tbone@cpan.org>

Thanks for Perrin Harkins for mentioning Config::ApacheFormat

Thanks for Sam Tregar for writing Config::ApacheFormat.

COPYRIGHT AND LICENSE

Copyright 2003 by Terrence Brannon

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

Many thanks for Dan Kubb for his input on this module and also for alerting me to new attributes as of DBI 1.45.