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 start_server { ... }

    sub stop_server  { ... }

    sub create_database {
        my ( $class, $name ) = @_;
        ...
        return $handle;
    }

DESCRIPTION

Test::Database::Driver is a base class for creating Test::Database drivers.

METHODS

The class provides the following methods:

name()

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. Typically used to configure the DSN or the database engine.

handle( [ $name ] )

Return a Test::Database::Handle object for a database named $name. If $name is not given, the name test_database is used.

cleanup()

Delete the base_dir() directory and its content.

When called on Test::Database directly, it will delete the main directory that contains all the individual directories used by Test::Database drivers.

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

init()

The method does the general configuration needed for a database driver. All drivers should start by calling __PACKAGE__->init() to ensure they have been correctly initialized.

username()

Return the username of the user running the current program.

run_cmd( $cmd, @args )

Run the requested command using system(). Will die() in case of a problem (non-zero exit status, signal).

spawn_cmd( $cmd, @args )

Create a new process to run the requested command. Will die() in case of a problem.

Will use fork()+exec() on Unix systems, and Win32::Process::Create under Win32 systems.

available_port()

Return an available TCP port (useful for setting up a TCP server).

is_engine_setup()

is_engine_started()

Routines that let the driver know if the engine has been setup or started. (Used internally.)

WRITING A DRIVER FOR YOUR DATABASE OF CHOICE

Creating a driver requires writing the following methods:

setup_engine()

Setup the corresponding database engine, and return a true value corresponding to the configuration information needed to start the database engine and to create new databases.

start_engine( $config )

Start the corresponding database engine, and return a true value if the server was successfully started (meaning it will need to be stopped).

$config is the return value from setup_engine().

Test::Database::Driver provides a default implementation if no startup is required.

stop_engine( $info )

Stops a running database engine.

$info is the return value of start_server(), which allows driver authors to pass information to the stop_engine() method.

Test::Database::Driver provides a default implementation if no shutdown is required.

create_database( $config, $name )

Create the database for the corresponding DBD driver.

$config is the return value from setup_engine().

Return a Test::Database::Handle in case of success, and nothing in case of failure to create the database.

AUTHOR

Philippe Bruhat (BooK), <book@cpan.org>

COPYRIGHT

Copyright 2008 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.