NAME¶
Test::Database::Driver - Base class for Test::Database drivers
SYNOPSIS¶
package Test::Database::Driver::MyDatabase;
use strict;
use warnings;
use Test::Database::Driver;
our @ISA = qw( Test::Database::Driver );
sub _version {
my ($class) = @_;
...;
return $version;
}
sub create_database {
my ( $self ) = @_;
...;
return $handle;
}
sub drop_database {
my ( $self, $name ) = @_;
...;
}
sub databases {
my ($self) = @_;
...;
return @databases;
}
DESCRIPTION¶
Test::Database::Driver is a base class for creating Test::Database drivers.
METHODS¶
The class provides the following methods:
new¶
my $driver = Test::Database::Driver->new( driver => 'SQLite' );
my $driver = Test::Database::Driver::SQLite->new();
Create a new Test::Database::Driver object.
If called as "Test::Database::Driver->new()", requires a
"driver" parameter to define the actual object class.
make_handle¶
my $handle = $driver->make_handle();
Create a new Test::Database::Handle object, attached to an existing database or
to a newly created one.
The decision whether to create a new database or not is made by
Test::Database::Driver based on the information in the mapper. See
"TEMPORARY STORAGE ORGANIZATION" for details.
make_dsn¶
my $dsn = $driver->make_dsn( %args )
Return a Data Source Name based on the driver's DSN, with the key/value pairs
contained in %args as additional parameters.
This is typically used by "dsn()" to make a DSN for a specific
database, based on the driver's DSN.
name¶
dbd¶
my $name = $driver->dbd;
The driver's short name (everything after "Test::Database::Driver::").
base_dir¶
my $dir = $driver->base_dir;
The directory where the driver should store all the files for its databases, if
needed. Typically used by file-based database drivers.
version¶
my $db_version = $driver->version;
"version" object representing the version of the underlying database
enginge. This object is build with the return value of "_version()".
version_string¶
my $db_version = $driver->version_string;
Version string representing the version of the underlying database enginge. This
string is the actual return value of "_version()".
dbd_version¶
my $dbd_version = $driver->dbd_version;
The version of the DBD used to connect to the database engine, as returned by
"VERSION()".
driver_dsn¶
my $dsn = $driver->driver_dsn;
Return a driver Data Source Name, sufficient to connect to the database engine
without specifying an actual database.
username¶
my $username = $driver->username;
Return the connection username. Defaults to "undef".
password¶
my $password = $driver->password;
Return the connection password. Defaults to "undef".
connection_info()¶
my @info = $driver->connection_info;
Return the connection information triplet ("driver_dsn",
"username", "password").
version_matches¶
if ( $driver->version_matches($request) ) {
...;
}
Return a boolean indicating if the driver's version matches the version
constraints in the given request (see Test::Database documentation's section
about requests).
METHODS FOR DRIVER AUTHORS¶
The class also provides a few helpful commands that may be useful for driver
authors:
available_dbname¶
my $dbname = $self->available_dbname();
Return an unused database name that can be used to create a new database for the
driver.
dsn¶
my $dns = $self->dsn( $dbname )
Build a Data Source Name for the database with the given $dbname, based on the
driver's DSN.
WRITING A DRIVER FOR YOUR DATABASE OF CHOICE¶
The SYNOPSIS contains a good template for writing a Test::Database::Driver
class.
Creating a driver requires writing the following methods:
_version¶
my $version = $driver->_version;
Return the version of the underlying database engine.
create_database¶
$driver->create_database( $name );
Create the database for the corresponding DBD driver.
Return a Test::Database::Handle in case of success, and nothing in case of
failure to create the database.
drop_database( $name )¶
$driver->drop_database( $name );
Drop the database named $name.
OVERRIDABLE METHODS WHEN WRITING A DRIVER¶
Some methods have defaults implementations in Test::Database::Driver, but those
can be overridden in the derived class:
is_filebased¶
Return a boolean value indicating if the database engine is file-based or not,
i.e. if all the database information is stored in a file or a directory, and
no external database server is needed.
databases¶
my @db = $driver->databases();
Return the names of all existing databases for this driver as a list (the
default implementation is only valid for file-based drivers).
TEMPORARY STORAGE ORGANIZATION¶
Subclasses of Test::Database::Driver store useful information in the system's
temporary directory, under a directory named
Test-Database-$user ($user
being the current user's name).
That directory contains the following files:
- database files
- The database files and directories created by file-based drivers
controlled by Test::Database are stored here, under names matching
tdd_ DRIVER_N, where
DRIVER is the lowercased name of the driver and N is a
number.
- the mapping.yml file
- A YAML file containing a "cwd()" / database name mapping, to
enable a given test suite to receive the same database handles in all the
test scripts that call the "Test::Database->handles()"
method.
AUTHOR¶
Philippe Bruhat (BooK), "<book@cpan.org>"
COPYRIGHT¶
Copyright 2008-2010 Philippe Bruhat (BooK), all rights reserved.
LICENSE¶
This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.