Source code hosting provided by the generous |
Click here for the DBIx::Connect project page. |
COPYRIGHT NOTICE:
This software, a Perl package named DBIx::Connect, is released under the same copyright terms as Perl itself.
DBIx::Connect - DBI, DBIx::AnyDBD, and Alzabo database connection (info) via AppConfig
# .cshrc setenv APPCONFIG /Users/metaperl/.appconfig setenv DBIX_CONN "${APPCONFIG}-dbi" # Note that the DBIX_CONN environment variable is now optional - # a file can be specified using the command line parameter # -dbix_conn_file, e.g.: perl dbi_script.pl -dbix_conn_file /Users/metaperl/.appconfig-dbi # Any number of blocks may be specified in the config file - one block # per connection handle. Any of the options specified in the file # can be overridden # by using the command line syntax shown below. # .appconfig-dbi [basic] user= postgres pass = <STDIN> dsn= dbi:Pg:dbname=mydb attr RaiseError = 0 attr PrintError = 0 attr Taint = 1 [dev_db] user = root pass = w00t! dsn = dbi:mysql:database=mysqldb;host=localhost attr RaiseError = 1 attr PrintError = 1 # DBIx::AnyDBD usage: my @connect_data = DBIx::Connect->data_array('dev_db'); my $dbh = DBIx::AnyDBD->connect(@connect_data, "MyClass"); # Alzabo usage my %connect_data = DBIx::Connect->data_hash('dev_db'); # pure DBI usage use DBIx::Connect; my $dbh = DBIx::Connect->to('dev_db'); # over-ride .appconfig-dbi from the command line # not recommended for passwords as C<ps> will reveal the password perl dbi-script.pl basic -dbix_conn_file .appconfig-dbi \ -basic_user tim_bunce -basic_pass dbi_rocks perl dbi-script.pl basic -basic_attr "RaiseError=1" \ -basic_attr "Taint=0" # Note that all parameters can be specified on the command line, # so the file is not strictly necessary. As a practical matter, # this is not a likely scenario, but it is supported. perl dbi-script.pl -basic_user basic -basic_pass "<STDIN>" \ -basic_dsn "dbi:Pg:dbname=basic" -basic_attr "AutoCommit=0"
DBIx::Connect will croak wth the DBI error if it cannot create a valid database handle.
This module facilitates DBI -style, DBIx::AnyDBD -style, or Alzabo -style database connections for sites and applications which make use of AppConfig and related modules to configure their applications via files and/or command-line arguments.
It provides three methods, to
, data_array
, and data_hash
which return a DBI database handle and an array of DBI connection info,
respectively.
Each of the 4 DBI connection parameters (username, password, dsn, attr) can be defined via any of the methods supported by AppConfig, meaning via a configuration file, or simple-style command-line arguments. AppConfig also provides support for both simple and Getopt::Long style, but Getopt::Long is overkill for a module this simple.
In order to preserve maximum flexibility, DBIx::Connect does not do any verification of completeness or correctness of connection parameters, deferring these checks to the DBI itself. This is because different drivers (and the DBI itself) can use environment variables (or nothing) to represent valid connection attributes.
DBIx::Connect maintains a strict priority for overlay of connection paramters:
* Environment variables * Config file options * Command line parameters
This means that if the user attribute for a connection block is not specified either by the file or command line, undef will be sent to the DBI, which will instruct it to examine DBI_PASS, if defined, or send undef to the database, which is common with certain databases.
The only module similar to this on CPAN is DBIx::Password. Here are some points of comparison/contrast.
The advantage of a config file is that each programmer can have his own config file whereas it could prove tedious for each programmer to have his own personal copy of a Perl configuration module.
Not to mention the fact that if each Perl module in your large application went this route, you would be stuck with n-fold Perl configuration modules as opposed to one centralized AppConfig file. For example, my module SQL::Catalog, used to use on-the-fly Config modules and Net::FTP::Common did as well.
In contrast, DBIx::Connect can add configuration information upon
invocation via the command-line or via the read-from-STDIN-flag
,
<STDIN
>, which will overwrite or set arguments which
could have been in the configuration file, which means your passwords need not
be stored on disk at all.
connect
which returns a $dbh
. While
DBIx::Connect also supplies such a method (named to
), it also supplies a
data_hash
and data_array
method which can be passed to
any other DBI connection scheme, the must ubiquitous of which are Alzabo and
DBIx::AnyDBD, which handles connections for you after you give it the
connection data.
I submitted a patch to the author of DBIx::Password to support such functionality, but it was rejected on the grounds that DBIx::Password is designed to secure connection data, not make it available in any form or fashion.
From now on, any module of mine which requires configuration info will use AppConfig to get it. I thought about using XML but a discussion on Perlmonks.Org and one on p5ee@perl.org both made strong arguments in favor of AppConfig.
None by default.
T. M. Brannon <tbone@cpan.org> and Martin Jackson <mhjacks - NOSPAN - at - swbell - dot - net>
The args method of AppConfig::Args is called on a copy of @ARGV, not the actual @ARGV. This allows us to reparse command line arguments multiple times, for multiple calls within the same script/module. The only (possibly) negative effect of this is that the elements of @ARGV will not be consumed as they normally would be by the args method. Be aware of this if you are parsing command line options besides the DBIx::Connect ones.