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.