1Test::Database::Driver(U3s)er Contributed Perl DocumentatTieosnt::Database::Driver(3)
2
6 Test::Database::Driver - Base class for Test::Database drivers
7
9 package Test::Database::Driver::MyDatabase;
10 use strict;
11 use warnings;
12 use Test::Database::Driver;
14 our @ISA = qw( Test::Database::Driver );
15 sub _version {
17 my ($class) = @_;
18 ...;
19 return $version;
20 }
21 sub create_database {
23 my ( $self ) = @_;
24 ...;
25 return $handle;
26 }
27 sub drop_database {
29 my ( $self, $name ) = @_;
30 ...;
31 }
32 sub databases {
34 my ($self) = @_;
35 ...;
36 return @databases;
37 }
38
40 Test::Database::Driver is a base class for creating Test::Database
41 drivers.
42
44 The class provides the following methods:
45 new
47 my $driver = Test::Database::Driver->new( driver => 'SQLite' );
48 my $driver = Test::Database::Driver::SQLite->new();
50 Create a new Test::Database::Driver object.
52 If called as "Test::Database::Driver->new()", requires a "driver"
54 parameter to define the actual object class.
55 make_handle
57 my $handle = $driver->make_handle();
58 Create a new Test::Database::Handle object, attached to an existing
60 database or to a newly created one.
61 The decision whether to create a new database or not is made by
63 Test::Database::Driver based on the information in the mapper. See
64 "TEMPORARY STORAGE ORGANIZATION" for details.
65 make_dsn
67 my $dsn = $driver->make_dsn( %args )
68 Return a Data Source Name based on the driver's DSN, with the key/value
70 pairs contained in %args as additional parameters.
71 This is typically used by "dsn()" to make a DSN for a specific
73 database, based on the driver's DSN.
74 name
76 dbd
77 my $name = $driver->dbd;
78 The driver's short name (everything after "Test::Database::Driver::").
80 base_dir
82 my $dir = $driver->base_dir;
83 The directory where the driver should store all the files for its
85 databases, if needed. Typically used by file-based database drivers.
86 version
88 my $db_version = $driver->version;
89 "version" object representing the version of the underlying database
91 enginge. This object is build with the return value of "_version()".
92 version_string
94 my $db_version = $driver->version_string;
95 Version string representing the version of the underlying database
97 enginge. This string is the actual return value of "_version()".
98 dbd_version
100 my $dbd_version = $driver->dbd_version;
101 The version of the DBD used to connect to the database engine, as
103 returned by "VERSION()".
104 driver_dsn
106 my $dsn = $driver->driver_dsn;
107 Return a driver Data Source Name, sufficient to connect to the database
109 engine without specifying an actual database.
110 username
112 my $username = $driver->username;
113 Return the connection username. Defaults to "undef".
115 password
117 my $password = $driver->password;
118 Return the connection password. Defaults to "undef".
120 connection_info()
122 my @info = $driver->connection_info;
123 Return the connection information triplet ("driver_dsn", "username",
125 "password").
126 version_matches
128 if ( $driver->version_matches($request) ) {
129 ...;
130 }
131 Return a boolean indicating if the driver's version matches the version
133 constraints in the given request (see Test::Database documentation's
134 section about requests).
135
137 The class also provides a few helpful commands that may be useful for
138 driver authors:
139 available_dbname
141 my $dbname = $self->available_dbname();
142 Return an unused database name that can be used to create a new
144 database for the driver.
145 dsn
147 my $dns = $self->dsn( $dbname )
148 Build a Data Source Name for the database with the given $dbname, based
150 on the driver's DSN.
151
153 The SYNOPSIS contains a good template for writing a
154 Test::Database::Driver class.
155 Creating a driver requires writing the following methods:
157 _version
159 my $version = $driver->_version;
160 Return the version of the underlying database engine.
162 create_database
164 $driver->create_database( $name );
165 Create the database for the corresponding DBD driver.
167 Return a Test::Database::Handle in case of success, and nothing in case
169 of failure to create the database.
170 drop_database( $name )
172 $driver->drop_database( $name );
173 Drop the database named $name.
175
177 Some methods have defaults implementations in Test::Database::Driver,
178 but those can be overridden in the derived class:
179 is_filebased
181 Return a boolean value indicating if the database engine is file-based
182 or not, i.e. if all the database information is stored in a file or a
183 directory, and no external database server is needed.
184 databases
186 my @db = $driver->databases();
187 Return the names of all existing databases for this driver as a list
189 (the default implementation is only valid for file-based drivers).
190
192 Subclasses of Test::Database::Driver store useful information in the
193 system's temporary directory, under a directory named
194 Test-Database-$user ($user being the current user's name).
195 That directory contains the following files:
197 database files
199 The database files and directories created by file-based drivers
200 controlled by Test::Database are stored here, under names matching
201 tdd_DRIVER_N, where DRIVER is the lowercased name of the driver and
202 N is a number.
203 the mapping.yml file
205 A YAML file containing a "cwd()" / database name mapping, to enable
206 a given test suite to receive the same database handles in all the
207 test scripts that call the "Test::Database->handles()" method.
208
210 Philippe Bruhat (BooK), "<book@cpan.org>"
211
213 Copyright 2008-2010 Philippe Bruhat (BooK), all rights reserved.
214
216 This module is free software; you can redistribute it and/or modify it
217 under the same terms as Perl itself.
218perl v5.34.0 2022-01-21 Test::Database::Driver(3)