GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  DBIX::CLASS::SCHEMA::CONFIG (3)

.ds Aq ’

NAME

DBIx::Class::Schema::Config - Credential Management for DBIx::Class

CONTENTS

DESCRIPTION

DBIx::Class::Schema::Config is a subclass of DBIx::Class::Schema that allows the loading of credentials from a file. The actual code itself would only need to know about the name used in the configuration file. This aims to make it simpler for operations teams to manage database credentials.

A simple tutorial that compliments this documentation and explains converting an existing DBIx::Class Schema to usingthis software to manage credentials can be found at <http://www.symkat.com/credential-management-in-dbix-class>

SYNOPSIS



    /etc/dbic.yaml
    MY_DATABASE:
        dsn: "dbi:Pg:host=localhost;database=blog"
        user: "TheDoctor"
        password: "dnoPydoleM"
        TraceLevel: 1

    package My::Schema
    use warnings;
    use strict;

    use base DBIx::Class::Schema::Config;
    __PACKAGE__->load_namespaces;

    package My::Code;
    use warnings;
    use strict;
    use My::Schema;

    my $schema = My::Schema->connect(MY_DATABASE);



CONFIG FILES

This module will load the files in the following order if they exist:
o $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



o ./dbic.*
o ~/.dbic.*
o /etc/dbic.*
The files should have an extension that Config::Any recognizes, for example /etc/dbic.<B>yamlB>.

NOTE: The first available credential will be used. Therefore DATABASE in ~/.dbic.yaml will only be looked at if it was not found in ./dbic.yaml. If there are duplicates in one file (such that DATABASE is listed twice in ~/.dbic.yaml,) the first configuration will be used.

CHANGE CONFIG PATH

Use __PACKAGE__->config_paths([( /file/stub, /var/www/etc/dbic)]); to change the paths that are searched. For example:



    package My::Schema
    use warnings;
    use strict;

    use base DBIx::Class::Schema::Config;
    __PACKAGE__->config_paths([( /var/www/secret/dbic, /opt/database )]);



The above code would have /var/www/secret/dbic.* and /opt/database.* searched, in that order. As above, the first credentials found would be used. This will replace the files origionally searched for, not add to them.

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.



    package My::Schema
    use warnings;
    use strict;

    use base DBIx::Class::Schema::Config;
    __PACKAGE__->config_files([( /var/www/secret/dbic.yaml, /opt/database.yaml )]);



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

The API has been designed to be simple to override if you have additional needs in loading DBIC configurations.

    filter_loaded_credentials

Override this function if you want to change the loaded credentials before they are passed to DBIC. This is useful for use-cases that include decrypting encrypted passwords or making progamatic changes to the configuration before using it.



    sub filter_loaded_credentials {
        my ( $class, $loaded_credentials, $connect_args ) = @_;
        ...
        return $loaded_credentials;
    }



$loaded_credentials is the structure after it has been loaded from the configuration file. In this case, $loaded_credentials->{user} eq <B>WalterWhiteB> and $loaded_credentials->{dsn} eq <B>DBI:mysql:database=students;host=%s;port=3306B>.

$connect_args is the structure originally passed on ->connect() after it has been turned into a hash. For instance, ->connect(DATABASE, USERNAME) will result in $connect_args->{dsn} eq <B>DATABASEB> and $connect_args->{user} eq <B>USERNAMEB>.

Additional parameters can be added by appending a hashref, to the connection call, as an example, ->connect( CONFIG, { hostname => "db.foo.com" } ); will give $connect_args a structure like { dsn => CONFIG, hostname => "db.foo.com" }.

For instance, if you want to use hostnames when you make the initial connection to DBIC and are using the configuration primarily for usernames, passwords and other configuration data, you can create a config like the following:



    DATABASE:
        dsn: "DBI:mysql:database=students;host=%s;port=3306"
        user: "WalterWhite"
        password: "relykS"



In your Schema class, you could include the following:



    package My::Schema
    use warnings;
    use strict;
    use base DBIx::Class::Schema::Config;

    sub filter_loaded_credentials {
        my ( $class, $loaded_credentials, $connect_args ) = @_;
        if ( $loaded_credentials->{dsn} =~ /\%s/ ) {
            $loaded_credentials->{dsn} = sprintf( $loaded_credentials->{dsn},
                $connect_args->{hostname});
        }
    }
   
    __PACKAGE__->load_classes;
    1;



Then the connection could be done with $Schema->connect(DATABASE, { hostname = ’my.hostname.com’ });>

See load_credentials for more complex changes that require changing how the configuration itself is loaded.

    load_credentials

Override this function to change the way that DBIx::Class::Schema::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}



    Some::Schema->connect(
        "SomeTarget",
        "Yuri",
        "Yawny",
        {
            TraceLevel => 1
        }
    );



Would result in the following data structure as $config in load_credentials($class, $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:



    package My::Schema
    use warnings;
    use strict;
    use base DBIx::Class::Schema::Config;
    use LWP::Simple;
    use JSON

    # Load credentials from internal web server.
    sub load_credentials {
        my ( $class, $config ) = @_;

        return decode_json(
            get( "http://someserver.com/v1.0/database?key=somesecret&db=" .
                $config->{dsn}  ));
    }
   
    __PACKAGE__->load_classes;



AUTHOR

Kaitlyn Parkhurst (SymKat) <symkat@symkat.com> ( Blog: <http://symkat.com/> )

CONTRIBUTORS

o Matt S. Trout (mst) <mst@shadowcat.co.uk>
o Peter Rabbitson (ribasushi) E<li>ribasushi@cpan.orgE<GT>
o Christian Walde <walde.christian@googlemail.com>

COPYRIGHT AND 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-Class-Schema-Config>

POD ERRORS

Hey! <B>The above document had some coding errors, which are explained below:B>
Around line 332: Unknown E content in E<li>

Unknown E content in E<GT>

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 DBIX::CLASS::SCHEMA::CONFIG (3) 2012-09-18

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.