1Test::Database(3)     User Contributed Perl Documentation    Test::Database(3)
2
3
4

NAME

6       Test::Database - Database handles ready for testing
7

SYNOPSIS

9       Maybe you wrote generic code you want to test on all available
10       databases:
11
12           use Test::More;
13           use Test::Database;
14
15           # get all available handles
16           my @handles = Test::Database->handles();
17
18           # plan the tests
19           plan tests => 3 + 4 * @handles;
20
21           # run the tests
22           for my $handle (@handles) {
23               diag "Testing with " . $handle->dbd();    # mysql, SQLite, etc.
24
25               # there are several ways to access the dbh:
26
27               # let $handle do the connect()
28               my $dbh = $handle->dbh();
29
30               # do the connect() yourself
31               my $dbh = DBI->connect( $handle->connection_info() );
32               my $dbh = DBI->connect( $handle->dsn(), $handle->username(),
33                   $handle->password() );
34           }
35
36       It's possible to limit the results, based on the databases your code
37       supports:
38
39           my @handles = Test::Database->handles(
40               'SQLite',                 # SQLite database
41               { dbd    => 'mysql' },    # or mysql database
42               { driver => 'Pg' },       # or Postgres database
43           );
44
45           # use them as above
46
47       If you only need a single database handle, all the following return the
48       same one:
49
50           my $handle   = ( Test::Database->handles(@requests) )[0];
51           my ($handle) = Test::Database->handles(@requests);
52           my $handle   = Test::Database->handles(@requests);    # scalar context
53           my $handle   = Test::Database->handle(@requests);     # singular!
54           my @handles  = Test::Database->handle(@requests);     # one or zero item
55
56       You can use the same requests again if you need to use the same test
57       databases over several test scripts.
58

DESCRIPTION

60       Test::Database provides a simple way for test authors to request a test
61       database, without worrying about environment variables or the test host
62       configuration.
63
64       See SYNOPSIS for typical usage.
65
66       See Test::Database::Tutorial for more detailed explanations.
67

METHODS

69       Test::Database provides the following methods:
70
71   list_drivers
72           my @drivers = Test::Database->list_drivers();
73           my @drivers = Test::Database->list_drivers('available');
74
75       Return a list of driver names of the given "type".
76
77       "all" returns the list of all existing Test::Database::Driver
78       subclasses.
79
80       "available" returns the list of Test::Database::Driver subclasses for
81       which the matching "DBD" class is available.
82
83       Called with no parameter (or anything not matching "all" or
84       "available"), it will return the list of currently loaded drivers.
85
86   drivers
87       Returns the Test::Database::Driver instances that are setup by
88       load_drivers() and updated by load_config().
89
90   load_drivers
91       Load the available drivers from the system (file-based drivers,
92       usually).
93
94   load_config
95           Test::Database->load_config($config);
96
97       Read configuration from the files in @files.
98
99       If no file is provided, the local equivalent of ~/.test-database is
100       used.
101
102   clean_config
103           Test::Database->clean_config();
104
105       Empties whatever configuration has already been loaded.  Also removes
106       the loaded drivers list.
107
108   handles
109           my @handles = Test::Database->handles(@requests);
110
111       Return a set of Test::Database::Handle objects that match the given
112       @requests.
113
114       If @requests is not provided, return all the available handles.
115
116       See REQUESTS for details about writing requests.
117
118   handle
119           my $handle = Test::Database->handle(@requests);
120
121       Singular version of handles(), that returns the first matching handle.
122

REQUESTS

124       The handles() method takes requests as parameters. A request is a
125       simple hash reference, with a number of recognized keys.
126
127       •   "dbd": driver name (based on the "DBD::" name).
128
129           "driver" is an alias for "dbd".  If the two keys are present, the
130           "driver" key will be ignored.
131
132           If missing, all available drivers will match.
133
134       •   "version": exact database engine version
135
136           Only database engines having a version string identical to the
137           given version string will match.
138
139       •   "min_version": minimum database engine version
140
141           Only database engines having a version number greater or equal to
142           the given minimum version will match.
143
144       •   "max_version": maximum database engine version
145
146           Only database engines having a version number lower (and not equal)
147           to the given maximum version will match.
148
149       •   "regex_version": matching database engine version
150
151           Only database engines having a version string that matches the
152           given regular expression will match.
153
154       A request can also consist of a single string, in which case it is
155       interpreted as a shortcut for "{ dbd =" $string }>.
156

FILES

158       The list of available, authorized DSN is stored in the local equivalent
159       of ~/.test-database. It's a simple list of key/value pairs, with the
160       "dsn", "driver_dsn" or "key" keys being used to split successive
161       entries:
162
163           # mysql
164           dsn      = dbi:mysql:database=mydb;host=localhost;port=1234
165           username = user
166           password = s3k r3t
167
168           # Oracle
169           dsn      = dbi:Oracle:test
170
171           # set a unique key when creating databases
172           key = thwapp
173
174           # a "driver" with full access (create/drop databases)
175           driver_dsn = dbi:mysql:
176           username   = root
177
178       The "username" and "password" keys are optional and "undef" will be
179       used if they are not provided.
180
181       Empty lines and comments are ignored.
182
183       Optionaly, the "key" section is used to add a "unique" element to the
184       databases created by the drivers (as defined by "driver_dsn"). It
185       allows several hosts to share access to the same database server
186       without risking a race condition when creating a new database. See
187       Test::Database::Tutorial for a longer explanation.
188
189       Individual drivers may accept extra parameters. See their documentation
190       for details. Unrecognized parameters and not used, and therefore
191       ignored.
192

AUTHOR

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

BUGS

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

SUPPORT

204       You can find documentation for this module with the perldoc command.
205
206           perldoc Test::Database
207
208       You can also look for information at:
209
210       •   RT: CPAN's request tracker
211
212           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Database>
213
214       •   AnnoCPAN: Annotated CPAN documentation
215
216           <http://annocpan.org/dist/Test-Database>
217
218       •   CPAN Ratings
219
220           <http://cpanratings.perl.org/d/Test-Database>
221
222       •   Search CPAN
223
224           <http://search.cpan.org/dist/Test-Database>
225

TODO

227       Some of the items on the TODO list:
228
229       •   Add a database engine autodetection script/module, to automatically
230           write the .test-database configuration file.
231

HISTORY

233       Quoting Michael Schwern:
234
235       There's plenty of modules which need a database, and they all have to
236       be configured differently and they're always a PITA when you first
237       install and each and every time they upgrade.
238
239       User setup can be dealt with by making Test::Database a build
240       dependency. As part of Test::Database's install process it walks the
241       user through the configuration process. Once it's done, it writes out a
242       config file and then it's done for good.
243
244       See <http://www.nntp.perl.org/group/perl.qa/2008/10/msg11645.html> for
245       the thread that led to the creation of Test::Database.
246

ACKNOWLEDGEMENTS

248       Thanks to "<perl-qa@perl.org>" for early comments.
249
250       Thanks to Nelson Ferraz for writing DBIx::Slice, the testing of which
251       made me want to have a generic way to obtain a test database.
252
253       Thanks to Mark Lawrence for discussing this module with me, and sending
254       me an alternative implementation to show me what he needed.
255
256       Thanks to Kristian Koehntopp for helping me write a mysql driver, and
257       to Greg Sabino Mullane for writing a full Postgres driver, none of
258       which made it into the final release because of the complete change in
259       goals and implementation between versions 0.02 and 0.03.
260
261       The work leading to the new implementation (version 0.99 and later) was
262       carried on during the Perl QA Hackathon, held in Birmingham in March
263       2009. Thanks to Birmingham.pm for organizing it and to Booking.com for
264       sending me there.
265
266       Thanks to the early adopters: Alexis Sukrieh (SUKRIA), Nicholas Bamber
267       (SILASMONK) and Adam Kennedy (ADAMK).
268

COPYRIGHT

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

LICENSE

273       This module is free software; you can redistribute it and/or modify it
274       under the same terms as Perl itself.
275
276
277
278perl v5.38.0                      2023-07-21                 Test::Database(3)