--- name: "Test::Database::Driver" section: "3pm" platform: "linux" package: "libtest-database-perl" version: "1.113-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Test::Database::Driver" --- # Test::Database::Driver(3pm) Base class for Test::Database drivers ## 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), `""` ## 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.