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
122       handle.
123

REQUESTS

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

FILES

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

AUTHOR

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

BUGS

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

SUPPORT

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

TODO

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

HISTORY

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

ACKNOWLEDGEMENTS

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

COPYRIGHT

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

LICENSE

274       This module is free software; you can redistribute it and/or modify it
275       under the same terms as Perl itself.
276
277
278
279perl v5.30.1                      2020-01-30                 Test::Database(3)