Until now,
when a test script needed a database,
it either used SQLite (or some other easy to setup database),
or required some environment variables to be present,
or used default credentials,
or even set up the database by itself.

Most of those methods have pros and cons:

using SQLite

No setup needed,
but the test script can only use SQLite's dialect of SQL.
So much for portability across database engines.

using environment variables

The environment variables are different for every module to test,
and usually only the main developers/testers know about them.
Since most of the CPAN testers probably don't bother setting them up,
these modules are most certainly undertested.

using default credentials

Typically using 'root' and '' to connect to the test MySQL database,
these test script assume a default installation on the host system.
These credentials often provide full access to the database engine,
which is a security risk in itself (see below).

setting up the database by itself

This method usually uses the default credentials to access an account with enough privileges to create a database.
The host system data may be at risk!

@request is a list of "requests" for databases handles. Requests must declare the DBD they expect, and can optionaly add version-based limitations (only available for drivers supported by Test::Database).

The data contained in the database is never destroyed or cleaned up by Test::Database, so it's perfectly fine to have a startup script that will setup the necessary tables and test data, several tests scripts that will build and update the data, and a eventually a teardown script that will drop all created tables.

either a handle to a newly created database (created especially at the test script's request)

or a handle to an already existing database

There is no way for the test script to tell the difference.

In any case, the database is assumed to provide DROP TABLE and CREATE TABLE rights, and the test script is by definition allowed to do whatever it pleases with the tables that exist in the database.

Note that Test::Database supports any DSN, not just those for which it has a driver. If your module supports Oracle, you can add 'Oracle' to your list of requests, and if the host owner configured a dsn pointing at an Oracle database, then it will be available for your tests.

There is no need to add dsn sections for file-based drivers (at least the ones that have a corresponding Test::Database::Driver), since the module will automatically detect the available ones and create databases as needed.

To find out which of the DBD that Test::Database supports are installed, use the following one-liner:

dsn sections define the information needed to connect to a single database. Any database listed here can be used by any test script that requests it.

driver_dsn sections define the information needed to connect to a database engine (a "driver") with sufficient rights to run a CREATE DATABASE command. This allows Test::Database to create the databases on demand, thus ensuring every test suite will get a specific database.

If you have file-based database engine, there is nothing to setup, as Test::Database is able to detect available file-based engines and use them as needed.

Other database engines like mysql and Pg require a little more configuration. For example, here's the content of my ~/.test-database configuration file:

If you have a large scale testing setup, you may want to setup a single MySQL or Postgres instance for all your test hosts, rather than one per test host.

Databases created by Test::Database::Driver (using a configured driver_dsn have a name built after the following template: tdd_driver_login_n, where driver is the DBD name, login is the login of the user running Test::Database and n a number that

If the same database server is used by several host running Test::Database from the same user account, there is a race condition during with two different host may try to create the a database with the same name. A simple trick to avoid this is to add a key section to the ~/.test-database configuration file.

If the key entry exists, the template used by Test::Database::Driver to create new databases is tdd_driver_login_key_n.

When given a driver_dsn, Test::Database will use it to create a database for each test suite that requests one. Some mapping information is created to ensure the same test suite always receives a handle to the same database. (The mapping of test suite to database is based on the current working directory when Test::Database is loaded).

After a while, your database engine may fill up with unused test databases.

All drivers store their mapping information in the system's temporary directory, so the mapping information is relatively volatile, which implies more unused test databases (at least for non file-based drivers, since the file-based drivers store their database files in the system's temporary directory too).

The following one-liner will list all the existing databases that were created by Test::Database in your configured drivers:

Adding a new driver requires writing a corresponding Test::Database::Driver subclass, having the same name as the original DBD driver.

An example module is provided in eg/MyDriver.pm, and the other drivers can also be used as an example. See also the WRITING A DRIVER FOR YOUR DATABASE OF CHOICE section in the documentation for Test::Database::Driver.

Test::Database also maintains a list of Test::Database::Driver objects computed from the list of supported file-based drivers that are locally available and from the list in the configuration file.

The list of matching drivers is computed from the requests. Each driver is then requested to provide an existing database (using its existing mapping information) or to create one if needed, and returns the corresponding Test::Database::Handle objects.

So, without any configuration, Test::Database will only be able to provide file-based databases. It is also recommended to not put DSN or driver information for the file-based database engines that have a corresponding Test::Database::Driver class, since it will cause handles() to return several handles for the same database engine.