view release on metacpan or  search on metacpan

lib/DBIx/Admin/DSNManager.pm  view on Meta::CPAN

	catch
	{
		print "DBIx::Admin::DSNManager died. Error: $_";
	};

See scripts/synopsis.pl.

=head1 Description

L<DBIx::Admin::DSNManager> manages a file of DSNs, for both testing and production.

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.

L<DBIx::Admin::DSNManager> is a solution to this problem.

=head1 Database Creation

By design, L<DBIx::Admin::DSNManager> does not provide a create-database option.

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 L</The Format of dsn.ini> below.

=head1 Testing 'v' Production

Of course, you may have DSNs in dsn.ini which you don't want to be used for testing.

Here's a policy for handling such situations:

=over 4

=item 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.

=item 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.

=back

=head1 The Format of dsn.ini

On disk, dsn.ini is a typical INI-style file. In RAM it is a hashref of config options. E.g.:

	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.

=over 4

=item o Sections

Section names are unique, case-sensitive, strings.

So 2 Postgres sections might be:

	[Pg.1]
	...

	[Pg.2]
	...

=item o Connexion info within each section

Each section can have these keys:

=over 4

=item o A DSN string

A typical Postgres dsn would be:

dsn = dbi:Pg:dbname=test

A dsn key is mandatory within each section.

The DSN names the driver to use and the database.

=item o A Username string

E.g.: username = testuser

A username is optional.

If a username is not provided for a dsn, the empty string is used.

=item o A Password string

E.g.: password = testpass

A password is optional.

If a password is not provided for a dsn, the empty string is used.

=item o DSN Attributes as a hashref

E.g.: