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.