NAME

Synopsis

        #!/usr/bin/env perl

        use strict;
        use warnings;

        use DBIx::Admin::DSNManager;

        us Try::Tiny;

        # --------------------------

        try
        {
                my($man1) = DBIx::Admin::DSNManager -> new
                (
                        config  => {'Pg.1' => {dsn => 'dbi:Pg:dbname=test', username => 'me', active => 1} },
                        verbose => 1,
                );

                my($file_name) = '/tmp/dsn.ini';

                $man1 -> write($file_name);

                my($man2) = DBIx::Admin::DSNManager -> new
                (
                        file_name => $file_name,
                        verbose   => 1,
                );

                $man2 -> report;
        }
        catch
        {
                print "DBIx::Admin::DSNManager died. Error: $_";
        };

See scripts/synopsis.pl.

Description

The INI-style format was selected, rather than, say, using an SQLite database, so that casual users could edit the file without needing to know SQL and without having to install the command line program sqlite3.

Each DSN is normally for something requiring manual preparation, such as creating the database named in the DSN.

In the case of SQLite, etc, where manual intervention is not required, you can still put the DSN in dsn.ini.

One major use of this module is to avoid environment variable overload, since it is common to test Perl modules by setting the env vars $DBI_DSN, $DBI_USER and $DBI_PASS.

But then the problem becomes: What do you do when you want to run tests against a set of databases servers? Some modules define sets of env vars, one set per database server, with awkward and hard-to-guess names. This is messy and obscure.

DBIx::Admin::DSNManager is a solution to this problem.

Database Creation

For database servers like Postgres, MySQL, etc, you must create users, and give them the createdb privilege. Such actions are outside the scope of this module.

For database servers like SQLite, any code can create a database anyway, but you can use options in dsn.ini to indicate the DSN is inactive, or not to be used for testing. See "The Format of dsn.ini" below.

Testing 'v' Production

Here's a policy for handling such situations:

o An explicit use_for_testing flag

Each DSN in the file can be marked with the option 'use_for_testing = 0', to stop usage for testing, or 'use_for_testing = 1', to allow usage for testing.

The default is 0 - do not use for testing.

o An implicit DSN

For cases like SQLite, testing code can either look in dsn.ini, or manufacture a temporary directory and file name for testing.

This leads to a new question: If the testing code finds a DSN in dsn.ini which is marked use_for_testing = 0, should that code still generate another DSN for testing? My suggestions is: Yes, since the one in dsn.ini does not indicate that all possible DSNs should be blocked from testing.

The Format of dsn.ini

        config => {'Pg.1' => {dsn => 'dbi:Pg:dbname=test', ...}, 'Pg.2' => {...} }

where config is the name of the module getter/setter which provides access to the hashref.

o Sections

Section names are unique, case-sensitive, strings.

So 2 Postgres sections might be:

        [Pg.1]
        ...

        [Pg.2]
        ...
    

o Connexion info within each section

Each section can have these keys:

So, a sample dsn.ini file looks like:

        [Pg.1]
        dsn=dbi:Pg:dbname=test1
        username=user1
        password=pass1
        attributes = {AutoCommit => 1, PrintError => 0, RaiseError => 1}
        use_for_testing = 0

        [Pg.2]
        dsn=dbi:Pg:dbname=test2
        username=user2
        password=pass2
        active = 0
        use_for_testing = 1

        [SQLite.1]
        dsn=dbi:SQLite:dbname=/tmp/test.module.sqlite

This file is read by Config::Tiny. Check its docs for details, but there is one thing to be aware of: Config::Tiny does not recognize comments at the ends of lines. So:

key = value # A comment.

sets key to 'value # A comment.', which is probably not what you intended.

Constructor and Initialization

"new()" takes a hash of key/value pairs, some of which might be mandatory. Further, some combinations might be mandatory.

The keys are listed here in alphabetical order.

They are lower-case because they are (also) method names, meaning they can be called to set or get the value at any time.

But a warning: In some cases, setting them after this module has used the previous value, will have no effect. All such cases are documented (or should be).

o config => {...}

Specifies a hashref to use as the initial value of the internal config hashref which holds the set of DSNs.

This hashref is keyed by section name, with each key pointing to a hashref of dsn data. E.g.:

        config => {'Pg.1' => {dsn => 'dbi:Pg:dbname=test', ...}, 'Pg.2' => {...} }
    

Default: undef.

o file_name => $string

Specifies the name of the file holding the DSNs.

If specified, the code reads this file and populates the hashref returned by "config()".

This key is optional.

Default: ''.

o verbose => 0 | 1

Specify more or less output.

Default: 0.

Methods

Version Numbers

Repository

Support

<https://github.com/ronsavage/DBIx-Admin-DSNManager/issues>

Author

Home page: <http://savage.net.au/index.html>.

Copyright

        All Programs of mine are 'OSI Certified Open Source Software';
        you can redistribute them and/or modify them under the terms of
        The Artistic License, a copy of which is available at:
        http://www.opensource.org/licenses/index.html