1Test::Database::Driver(U3s)er Contributed Perl DocumentatTieosnt::Database::Driver(3)
2
3
4

NAME

6       Test::Database::Driver - Base class for Test::Database drivers
7

SYNOPSIS

9           package Test::Database::Driver::MyDatabase;
10           use strict;
11           use warnings;
12
13           use Test::Database::Driver;
14           our @ISA = qw( Test::Database::Driver );
15
16           sub _version {
17               my ($class) = @_;
18               ...;
19               return $version;
20           }
21
22           sub create_database {
23               my ( $self ) = @_;
24               ...;
25               return $handle;
26           }
27
28           sub drop_database {
29               my ( $self, $name ) = @_;
30               ...;
31           }
32
33           sub databases {
34               my ($self) = @_;
35               ...;
36               return @databases;
37           }
38

DESCRIPTION

40       Test::Database::Driver is a base class for creating Test::Database
41       drivers.
42

METHODS

44       The class provides the following methods:
45
46   new
47           my $driver = Test::Database::Driver->new( driver => 'SQLite' );
48
49           my $driver = Test::Database::Driver::SQLite->new();
50
51       Create a new Test::Database::Driver object.
52
53       If called as "Test::Database::Driver->new()", requires a "driver"
54       parameter to define the actual object class.
55
56   make_handle
57           my $handle = $driver->make_handle();
58
59       Create a new Test::Database::Handle object, attached to an existing
60       database or to a newly created one.
61
62       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
66   make_dsn
67           my $dsn = $driver->make_dsn( %args )
68
69       Return a Data Source Name based on the driver's DSN, with the key/value
70       pairs contained in %args as additional parameters.
71
72       This is typically used by "dsn()" to make a DSN for a specific
73       database, based on the driver's DSN.
74
75   name
76   dbd
77           my $name = $driver->dbd;
78
79       The driver's short name (everything after "Test::Database::Driver::").
80
81   base_dir
82           my $dir = $driver->base_dir;
83
84       The directory where the driver should store all the files for its
85       databases, if needed. Typically used by file-based database drivers.
86
87   version
88           my $db_version = $driver->version;
89
90       "version" object representing the version of the underlying database
91       enginge.  This object is build with the return value of "_version()".
92
93   version_string
94           my $db_version = $driver->version_string;
95
96       Version string representing the version of the underlying database
97       enginge.  This string is the actual return value of "_version()".
98
99   dbd_version
100           my $dbd_version = $driver->dbd_version;
101
102       The version of the DBD used to connect to the database engine, as
103       returned by "VERSION()".
104
105   driver_dsn
106           my $dsn = $driver->driver_dsn;
107
108       Return a driver Data Source Name, sufficient to connect to the database
109       engine without specifying an actual database.
110
111   username
112           my $username = $driver->username;
113
114       Return the connection username. Defaults to "undef".
115
116   password
117           my $password = $driver->password;
118
119       Return the connection password. Defaults to "undef".
120
121   connection_info()
122           my @info = $driver->connection_info;
123
124       Return the connection information triplet ("driver_dsn", "username",
125       "password").
126
127   version_matches
128           if ( $driver->version_matches($request) ) {
129               ...;
130           }
131
132       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

METHODS FOR DRIVER AUTHORS

137       The class also provides a few helpful commands that may be useful for
138       driver authors:
139
140   available_dbname
141           my $dbname = $self->available_dbname();
142
143       Return an unused database name that can be used to create a new
144       database for the driver.
145
146   dsn
147           my $dns = $self->dsn( $dbname )
148
149       Build a Data Source Name for the database with the given $dbname, based
150       on the driver's DSN.
151

WRITING A DRIVER FOR YOUR DATABASE OF CHOICE

153       The SYNOPSIS contains a good template for writing a
154       Test::Database::Driver class.
155
156       Creating a driver requires writing the following methods:
157
158   _version
159           my $version = $driver->_version;
160
161       Return the version of the underlying database engine.
162
163   create_database
164           $driver->create_database( $name );
165
166       Create the database for the corresponding DBD driver.
167
168       Return a Test::Database::Handle in case of success, and nothing in case
169       of failure to create the database.
170
171   drop_database( $name )
172           $driver->drop_database( $name );
173
174       Drop the database named $name.
175

OVERRIDABLE METHODS WHEN WRITING A DRIVER

177       Some methods have defaults implementations in Test::Database::Driver,
178       but those can be overridden in the derived class:
179
180   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
185   databases
186           my @db = $driver->databases();
187
188       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

TEMPORARY STORAGE ORGANIZATION

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
196       That directory contains the following files:
197
198       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
204       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

AUTHOR

210       Philippe Bruhat (BooK), "<book@cpan.org>"
211
213       Copyright 2008-2010 Philippe Bruhat (BooK), all rights reserved.
214

LICENSE

216       This module is free software; you can redistribute it and/or modify it
217       under the same terms as Perl itself.
218
219
220
221perl v5.34.0                      2022-01-21         Test::Database::Driver(3)
Impressum