debian man page for test::database::driver

Test::Database::Driver(3pm)				User Contributed Perl Documentation			       Test::Database::Driver(3pm)

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.

perl v5.10.1							    2010-11-27					       Test::Database::Driver(3pm)