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( %args )

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()

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( %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()

The driver's short name (everything after "Test::Database::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()

"version" object representing the version of the underlying database enginge. This object is build with the return value of "_version()".

version_string()

Version string representing the version of the underlying database enginge. This string is the actual return value of "_version()".

dbd_version()

The version of the DBD used to connect to the database engine, as returned by "VERSION()".

driver_dsn()

Return a driver Data Source Name, sufficient to connect to the database engine without specifying an actual database.

username()

Return the connection username.

password()

Return the connection password.

connection_info()

Return the connection information triplet ("driver_dsn", "username", "password").

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).

The class also provides a few helpful commands that may be useful for driver authors:

available_dbname()

Return an unused database name that can be used to create a new database for the driver.

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()

Return the version of the underlying database engine.

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 )

Drop the database named $name.

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()

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.