NAME
DBIx::Config - Manage credentials for DBI
DESCRIPTION
DBIx::Config wraps around DBI to provide a simple way of loading database credentials from a file. The aim is make it simpler for operations teams to manage database credentials.
SYNOPSIS
Given a file like /etc/dbi.yaml, containing:
MY_DATABASE:
dsn: "dbi:Pg:host=localhost;database=blog"
user: "TheDoctor"
password: "dnoPydoleM"
TraceLevel: 1The following code would allow you to connect the database:
#!/usr/bin/perl
use warnings;
use strict;
use DBIx::Config;
my $dbh = DBIx::Config->connect( "MY_DATABASE" );Of course, backwards compatibility is kept, so the following would also work:
#!/usr/bin/perl
use warnings;
use strict;
use DBIx::Config;
my $dbh = DBIx::Config->connect(
"dbi:Pg:host=localhost;database=blog",
"TheDoctor",
"dnoPydoleM",
{
TraceLevel => 1,
},
);For cases where you may use something like DBIx::Connector, a method is provided that will simply return the connection credentials:
!/usr/bin/perl
use warnings;
use strict;
use DBIx::Connector;
use DBIx::Config;
my $conn = DBIx::Connector->new(DBIx::Config->connect_info("MY_DATABASE"));CONFIG FILES
By default the following configuration files are examined, in order listed, for credentials. Configuration files are loaded with Config::Any. You should append the extention that Config::Any will recognize your file in to the list below. For instance ./dbic will look for files such as ./dbic.yaml, ./dbic.conf, etc. For documentation on acceptable files please see Config::Any. The first file which has the given credentials is used.
$ENV{DBIX_CONFIG_DIR}. '/dbic',$ENV{DBIX_CONFIG_DIR}can be configured at run-time, for instance:DBIX_CONFIG_DIR="/var/local/" ./my_program.pl$ENV{DBIX_CONFIG_DIR}. '/dbi',$ENV{DBIX_CONFIG_DIR}can be configured at run-time, for instance:DBIX_CONFIG_DIR="/var/local/" ./my_program.pl./dbic
./dbi
$HOME/.dbic
$HOME/.dbi
/etc/dbic
/etc/dbi
/etc/dbi
USE SPECIFIC CONFIG FILES
If you would rather explicitly state the configuration files you want loaded, you can use the class accessor config_files instead.
#!/usr/bin/perl
use warnings;
use strict;
use DBIx::Config
my $DBI = DBIx::Config->new( config_files => [
'/var/www/secret/dbic.yaml',
'/opt/database.yaml',
]);
my $dbh = $DBI->connect( "MY_DATABASE" );This will check the files, /var/www/secret/dbic.yaml, and /opt/database.yaml in the same way as config_paths, however it will only check the specific files, instead of checking for each extension that Config::Any supports. You MUST use the extension that corresponds to the file type you are loading. See Config::Any for information on supported file types and extension mapping.
OVERRIDING
config_files
The configuration files may be changed by setting an accessor:
#!/usr/bin/perl
use warnings;
use strict;
use DBIx::Config
my $DBI = DBIx::Config->new(config_paths => ['./dbcreds', '/etc/dbcreds']);
my $dbh = $DBI->connect( "MY_DATABASE" );This would check, in order, dbcreds in the current directory, and then /etc/dbcreds, checking for valid configuration file extentions appended to the given file.
filter_loaded_credentials
You may want to change the credentials that have been loaded, before they are used to connect to the DB. A coderef is taken that will allow you to make programatic changes to the loaded credentials, while giving you access to the origional data structure used to connect.
DBIx::Config->new(
filter_loaded_credentials => sub {
my ( $self, $loaded_credentials, $connect_args ) = @_;
...
return $loaded_credentials;
}
)Your coderef will take three arguments.
$self, the instance of DBIx::Config your code was called from. C$loaded_credentials, the credentials loaded from the config file.$connect_args, the normalized data structure of the initalconnectcall.
Your coderef should return the same structure given by $loaded_credentials.
As an example, the following code will use the credentials from /etc/dbi, but use its a hostname defined in the code itself.
/etc/dbi (note host=%s):
MY_DATABASE:
dsn: "DBI:mysql:database=students;host=%s;port=3306"
user: "WalterWhite"
password: "relykS"The Perl script:
#!/usr/bin/perl
use warnings;
use strict;
use DBIx::Config;
my $dbh = DBIx::Config->new(
# If we have %s, replace it with a hostname.
filter_loaded_credentials => sub {
my ( $self, $loaded_credentials, $connect_args ) = @_;
if ( $loaded_credentials->{dsn} =~ /\%s/ ) {
$loaded_credentials->{dsn} = sprintf(
$loaded_credentials->{dsn}, $connect_args->{hostname}
);
}
return $loaded_credentials;
}
)->connect( "MY_DATABASE", { hostname => "127.0.0.1" } );load_credentials
Override this function to change the way that DBIx::Config loads credentials. The function takes the class name, as well as a hashref.
If you take the route of having ->connect('DATABASE') used as a key for whatever configuration you are loading, DATABASE would be $config->{dsn}
$obj->connect(
"SomeTarget",
"Yuri",
"Yawny",
{
TraceLevel => 1
}
);Would result in the following data structure as $config in load_credentials($self, $config):
{
dsn => "SomeTarget",
user => "Yuri",
password => "Yawny",
TraceLevel => 1,
}Currently, load_credentials will NOT be called if the first argument to ->connect() looks like a valid DSN. This is determined by match the DSN with /^dbi:/i.
The function should return the same structure. For instance:
#!/usr/bin/perl
use warnings;
use strict;
use DBIx::Config;
use LWP::Simple;
use JSON;
my $DBI = DBIx::Config->new(
load_credentials => sub {
my ( $self, $config ) = @_;
return decode_json(
get( "http://someserver.com/v1.0/database?name=" . $config->{dsn} )
);
}
)
my $dbh = $DBI->connect( "MAGIC_DATABASE" );SEE ALSO
AUTHOR
Kaitlyn Parkhurst (SymKat) <symkat@symkat.com> (http://symkat.com/)
CONTRIBUTORS
Matt S. Trout (mst) <mst@shadowcat.co.uk>
COPYRIGHT
Copyright (c) 2012 the DBIx::Config "AUTHOR" and "CONTRIBUTORS" as listed above.
LICENSE
This library is free software and may be distributed under the same terms as perl itself.
AVAILABILITY
The latest version of this software is available at https://github.com/symkat/DBIx-Config