trusty (3) Test::Database::Driver.3pm.gz

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.