Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Test::Database(3)     User Contributed Perl Documentation    Test::Database(3)

       Test::Database -	Database handles ready for testing

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

	   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

	   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.

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

       See SYNOPSIS for	typical	usage.

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

       Test::Database provides the following methods:

	   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

       "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.

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

       Load the	available drivers from the system (file-based drivers,


       Read configuration from the files in @files.

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


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

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

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

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

       See REQUESTS for	details	about writing requests.

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

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

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

       o   "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.

       o   "version": exact database engine version

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

       o   "min_version": minimum database engine version

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

       o   "max_version": maximum database engine version

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

       o   "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 }>.

       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

	   # 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.

       Optionaly, 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

       Philippe	Bruhat (BooK), "<>"

       Please report any bugs or feature requests to "bug-test-database	at", or	through	the web	interface at
       <>.	I will
       be notified, and	then you'll automatically be notified of progress on
       your bug	as I make changes.

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

	   perldoc Test::Database

       You can also look for information at:

       o   RT: CPAN's request tracker


       o   AnnoCPAN: Annotated CPAN documentation


       o   CPAN	Ratings


       o   Search CPAN


       Some of the items on the	TODO list:

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

       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 <> for
       the thread that led to the creation of Test::Database.

       Thanks to "<>" 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 for organizing it and to for
       sending me there.

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

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

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

perl v5.32.0			  2014-05-24		     Test::Database(3)


Want to link to this manual page? Use this URL:

home | help