Provided by: libtest-database-perl_1.113-2_all bug

NAME

       Test::Database - Database handles ready for testing

SYNOPSIS

       Maybe you wrote generic code you want to test on all available databases:

           use Test::More;
           use Test::Database;

           # get all available handles
           my @handles = Test::Database->handles();

           # plan the tests
           plan tests => 3 + 4 * @handles;

           # run the tests
           for my $handle (@handles) {
               diag "Testing with " . $handle->dbd();    # mysql, SQLite, etc.

               # there are several ways to access the dbh:

               # let $handle do the connect()
               my $dbh = $handle->dbh();

               # do the connect() yourself
               my $dbh = DBI->connect( $handle->connection_info() );
               my $dbh = DBI->connect( $handle->dsn(), $handle->username(),
                   $handle->password() );
           }

       It's possible to limit the results, based on the databases your code supports:

           my @handles = Test::Database->handles(
               'SQLite',                 # SQLite database
               { dbd    => 'mysql' },    # or mysql database
               { driver => 'Pg' },       # or Postgres database
           );

           # use them as above

       If you only need a single database handle, all the following return the same one:

           my $handle   = ( Test::Database->handles(@requests) )[0];
           my ($handle) = Test::Database->handles(@requests);
           my $handle   = Test::Database->handles(@requests);    # scalar context
           my $handle   = Test::Database->handle(@requests);     # singular!
           my @handles  = Test::Database->handle(@requests);     # one or zero item

       You can use the same requests again if you need to use the same test databases over
       several test scripts.

DESCRIPTION

       Test::Database provides a simple way for test authors to request a test database, without
       worrying about environment variables or the test host configuration.

       See SYNOPSIS for typical usage.

       See Test::Database::Tutorial for more detailed explanations.

METHODS

       Test::Database provides the following methods:

   list_drivers
           my @drivers = Test::Database->list_drivers();
           my @drivers = Test::Database->list_drivers('available');

       Return a list of driver names of the given "type".

       "all" returns the list of all existing Test::Database::Driver subclasses.

       "available" returns the list of Test::Database::Driver subclasses for which the matching
       "DBD" class is available.

       Called with no parameter (or anything not matching "all" or "available"), it will return
       the list of currently loaded drivers.

   drivers
       Returns the Test::Database::Driver instances that are setup by "load_drivers()" and
       updated by "load_config()".

   load_drivers
       Load the available drivers from the system (file-based drivers, usually).

   load_config
           Test::Database->load_config($config);

       Read configuration from the files in @files.

       If no file is provided, the local equivalent of ~/.test-database is used.

   clean_config
           Test::Database->clean_config();

       Empties whatever configuration has already been loaded.  Also removes the loaded drivers
       list.

   handles
           my @handles = Test::Database->handles(@requests);

       Return a set of Test::Database::Handle objects that match the given @requests.

       If @requests is not provided, return all the available handles.

       See REQUESTS for details about writing requests.

   handle
           my $handle = Test::Database->handle(@requests);

       Singular version of "handles()", that returns the first matching handle.

REQUESTS

       The "handles()" method takes requests as parameters. A request is a simple hash reference,
       with a number of recognized keys.

       •   "dbd": driver name (based on the "DBD::" name).

           "driver" is an alias for "dbd".  If the two keys are present, the "driver" key will be
           ignored.

           If missing, all available drivers will match.

       •   "version": exact database engine version

           Only database engines having a version string identical to the given version string
           will match.

       •   "min_version": minimum database engine version

           Only database engines having a version number greater or equal to the given minimum
           version will match.

       •   "max_version": maximum database engine version

           Only database engines having a version number lower (and not equal) to the given
           maximum version will match.

       •   "regex_version": matching database engine version

           Only database engines having a version string that matches the given regular
           expression will match.

       A request can also consist of a single string, in which case it is interpreted as a
       shortcut for "{ dbd =" $string }>.

FILES

       The list of available, authorized DSN is stored in the local equivalent of
       ~/.test-database. It's a simple list of key/value pairs, with the "dsn", "driver_dsn" or
       "key" keys being used to split successive entries:

           # mysql
           dsn      = dbi:mysql:database=mydb;host=localhost;port=1234
           username = user
           password = s3k r3t

           # Oracle
           dsn      = dbi:Oracle:test

           # set a unique key when creating databases
           key = thwapp

           # a "driver" with full access (create/drop databases)
           driver_dsn = dbi:mysql:
           username   = root

       The "username" and "password" keys are optional and "undef" will be used if they are not
       provided.

       Empty lines and comments are ignored.

       Optionally, the "key" section is used to add a "unique" element to the databases created
       by the drivers (as defined by "driver_dsn"). It allows several hosts to share access to
       the same database server without risking a race condition when creating a new database.
       See Test::Database::Tutorial for a longer explanation.

       Individual drivers may accept extra parameters. See their documentation for details.
       Unrecognized parameters and not used, and therefore ignored.

AUTHOR

       Philippe Bruhat (BooK), "<book@cpan.org>"

BUGS

       Please report any bugs or feature requests to "bug-test-database at rt.cpan.org", or
       through the web interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Database>.  I will be notified, and
       then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

       You can find documentation for this module with the perldoc command.

           perldoc Test::Database

       You can also look for information at:

       •   RT: CPAN's request tracker

           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Database>

       •   AnnoCPAN: Annotated CPAN documentation

           <http://annocpan.org/dist/Test-Database>

       •   CPAN Ratings

           <http://cpanratings.perl.org/d/Test-Database>

       •   Search CPAN

           <http://search.cpan.org/dist/Test-Database>

TODO

       Some of the items on the TODO list:

       •   Add a database engine autodetection script/module, to automatically write the
           .test-database configuration file.

HISTORY

       Quoting Michael Schwern:

       There's plenty of modules which need a database, and they all have to be configured
       differently and they're always a PITA when you first install and each and every time they
       upgrade.

       User setup can be dealt with by making Test::Database a build dependency. As part of
       Test::Database's install process it walks the user through the configuration process. Once
       it's done, it writes out a config file and then it's done for good.

       See <http://www.nntp.perl.org/group/perl.qa/2008/10/msg11645.html> for the thread that led
       to the creation of Test::Database.

ACKNOWLEDGEMENTS

       Thanks to "<perl-qa@perl.org>" for early comments.

       Thanks to Nelson Ferraz for writing DBIx::Slice, the testing of which made me want to have
       a generic way to obtain a test database.

       Thanks to Mark Lawrence for discussing this module with me, and sending me an alternative
       implementation to show me what he needed.

       Thanks to Kristian Koehntopp for helping me write a mysql driver, and to Greg Sabino
       Mullane for writing a full Postgres driver, none of which made it into the final release
       because of the complete change in goals and implementation between versions 0.02 and 0.03.

       The work leading to the new implementation (version 0.99 and later) was carried on during
       the Perl QA Hackathon, held in Birmingham in March 2009. Thanks to Birmingham.pm for
       organizing it and to Booking.com for sending me there.

       Thanks to the early adopters: Alexis Sukrieh (SUKRIA), Nicholas Bamber (SILASMONK) and
       Adam Kennedy (ADAMK).

COPYRIGHT

       Copyright 2008-2010 Philippe Bruhat (BooK), all rights reserved.

LICENSE

       This module is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.