Test::Database(3pm)

✨ NAME ✨

Test::Database — database handles that are ready for testing 💖 this is a User Contributed Perl Documentation page for Test::Database(3pm), bestie.

---

🌸 SYNOPSIS 🌸

okay so. Maybe you wrote some generic code and you wanna test it on every database you can get your hands on? Say less:

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() );
}

And you can limit the results based on which databases your code actually 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 one single database handle, all of these give you the exact same one, no cap:

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

And here's the slay part: you can reuse the same requests if you need the same test databases across several test scripts. Obsessed. 🫶

---

🦋 DESCRIPTION 🦋

Test::Database gives test authors a simple way to request a test database without having to stress about environment variables or how the test host is configured. literally just ask for it. 💅

Peep the SYNOPSIS above for the typical usage.

And for the full lore, go read Test::Database::Tutorial — it explains everything in way more detail.

---

👑 METHODS 👑

Test::Database serves up the following methods, bestie:

🌈 list_drivers

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

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

• "all" — gives you the list of all existing Test::Database::Driver subclasses.
• "available" — gives you the list of Test::Database::Driver subclasses where the matching "DBD" class is actually available.

Call it with no parameter at all (or with anything that doesn't match "all" or "available"), and it hands you the list of currently loaded drivers.

💜 drivers

Returns the Test::Database::Driver instances that get set up by "load_drivers()" and updated by "load_config()". that's it, that's the method.

🎀 load_drivers

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

🌸 load_config

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

Reads 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 out whatever configuration has already been loaded. Also removes the loaded drivers list — so like, it's a full reset, periodt.

⭐ handles

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

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

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

See REQUESTS for the deets on how to write requests.

🍓 handle

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

The singular version of "handles()" — returns the first matching handle.

---

💅 REQUESTS 💅

The "handles()" method takes requests as parameters. A request is a simple hash reference with a handful of recognized keys. Here they are:

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

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

If it's missing, all available drivers will match.

• "version" — exact database engine version.

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

• "min_version" — minimum database engine version.

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

• "max_version" — maximum database engine version.

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

• "regex_version" — matching database engine version.

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

A request can also just be a single string, in which case it's interpreted as a shortcut for "{ dbd =" $string }>.

---

🦄 FILES 🦄

The list of available, authorized DSN lives 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 up 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're not provided.

Empty lines and comments are ignored. (as they should be, iconic behaviour ✨)

Optionally, the "key" section is used to add a "unique" element to the databases created by the drivers (as defined by "driver_dsn"). It lets several hosts 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 — check their documentation for details. Unrecognized parameters and not used, and therefore ignored.

---

💖 AUTHOR 💖

Philippe Bruhat (BooK), "<book@cpan.org>" — king behaviour, honestly. 👑

---

💀 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. bestie, that's a whole pipeline. 🔥

---

🫶 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. 😭 (they ate anyway, fr fr)

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.

---

and that's a wrap, bestie 🫶 this page is from perl v5.32.1, dated 2021-11-12 — thanks for reading my little Test::Database(3pm) TED talk, mwah 💅💖✨