.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Test::Database::Driver 3pm"
.TH Test::Database::Driver 3pm "2021-11-12" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test::Database::Driver \- Base class for Test::Database drivers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    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;
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Test::Database::Driver is a base class for creating Test::Database
drivers.
.SH "METHODS"
.IX Header "METHODS"
The class provides the following methods:
.SS "new"
.IX Subsection "new"
.Vb 1
\&    my $driver = Test::Database::Driver\->new( driver => \*(AqSQLite\*(Aq );
\&
\&    my $driver = Test::Database::Driver::SQLite\->new();
.Ve
.PP
Create a new Test::Database::Driver object.
.PP
If called as \f(CW\*(C`Test::Database::Driver\->new()\*(C'\fR, requires a \f(CW\*(C`driver\*(C'\fR
parameter to define the actual object class.
.SS "make_handle"
.IX Subsection "make_handle"
.Vb 1
\&    my $handle = $driver\->make_handle();
.Ve
.PP
Create a new Test::Database::Handle object, attached to an existing database
or to a newly created one.
.PP
The decision whether to create a new database or not is made by
Test::Database::Driver based on the information in the mapper.
See \*(L"\s-1TEMPORARY STORAGE ORGANIZATION\*(R"\s0 for details.
.SS "make_dsn"
.IX Subsection "make_dsn"
.Vb 1
\&    my $dsn = $driver\->make_dsn( %args )
.Ve
.PP
Return a Data Source Name based on the driver's \s-1DSN,\s0 with the key/value
pairs contained in \f(CW%args\fR as additional parameters.
.PP
This is typically used by \f(CW\*(C`dsn()\*(C'\fR to make a \s-1DSN\s0 for a specific database,
based on the driver's \s-1DSN.\s0
.SS "name"
.IX Subsection "name"
.SS "dbd"
.IX Subsection "dbd"
.Vb 1
\&    my $name = $driver\->dbd;
.Ve
.PP
The driver's short name (everything after \f(CW\*(C`Test::Database::Driver::\*(C'\fR).
.SS "base_dir"
.IX Subsection "base_dir"
.Vb 1
\&    my $dir = $driver\->base_dir;
.Ve
.PP
The directory where the driver should store all the files for its databases,
if needed. Typically used by file-based database drivers.
.SS "version"
.IX Subsection "version"
.Vb 1
\&    my $db_version = $driver\->version;
.Ve
.PP
\&\f(CW\*(C`version\*(C'\fR object representing the version of the underlying database enginge.
This object is build with the return value of \f(CW\*(C`_version()\*(C'\fR.
.SS "version_string"
.IX Subsection "version_string"
.Vb 1
\&    my $db_version = $driver\->version_string;
.Ve
.PP
Version string representing the version of the underlying database enginge.
This string is the actual return value of \f(CW\*(C`_version()\*(C'\fR.
.SS "dbd_version"
.IX Subsection "dbd_version"
.Vb 1
\&    my $dbd_version = $driver\->dbd_version;
.Ve
.PP
The version of the \s-1DBD\s0 used to connect to the database engine, as returned
by \f(CW\*(C`VERSION()\*(C'\fR.
.SS "driver_dsn"
.IX Subsection "driver_dsn"
.Vb 1
\&    my $dsn = $driver\->driver_dsn;
.Ve
.PP
Return a driver Data Source Name, sufficient to connect to the database
engine without specifying an actual database.
.SS "username"
.IX Subsection "username"
.Vb 1
\&    my $username = $driver\->username;
.Ve
.PP
Return the connection username. Defaults to \f(CW\*(C`undef\*(C'\fR.
.SS "password"
.IX Subsection "password"
.Vb 1
\&    my $password = $driver\->password;
.Ve
.PP
Return the connection password. Defaults to \f(CW\*(C`undef\*(C'\fR.
.SS "\fBconnection_info()\fP"
.IX Subsection "connection_info()"
.Vb 1
\&    my @info = $driver\->connection_info;
.Ve
.PP
Return the connection information triplet (\f(CW\*(C`driver_dsn\*(C'\fR, \f(CW\*(C`username\*(C'\fR,
\&\f(CW\*(C`password\*(C'\fR).
.SS "version_matches"
.IX Subsection "version_matches"
.Vb 3
\&    if ( $driver\->version_matches($request) ) {
\&        ...;
\&    }
.Ve
.PP
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).
.SH "METHODS FOR DRIVER AUTHORS"
.IX Header "METHODS FOR DRIVER AUTHORS"
The class also provides a few helpful commands that may be useful for driver
authors:
.SS "available_dbname"
.IX Subsection "available_dbname"
.Vb 1
\&    my $dbname = $self\->available_dbname();
.Ve
.PP
Return an unused database name that can be used to create a new database
for the driver.
.SS "dsn"
.IX Subsection "dsn"
.Vb 1
\&    my $dns = $self\->dsn( $dbname )
.Ve
.PP
Build a Data Source Name for the database with the given \f(CW$dbname\fR,
based on the driver's \s-1DSN.\s0
.SH "WRITING A DRIVER FOR YOUR DATABASE OF CHOICE"
.IX Header "WRITING A DRIVER FOR YOUR DATABASE OF CHOICE"
The \s-1SYNOPSIS\s0 contains a good template for writing a
Test::Database::Driver class.
.PP
Creating a driver requires writing the following methods:
.SS "_version"
.IX Subsection "_version"
.Vb 1
\&    my $version = $driver\->_version;
.Ve
.PP
Return the version of the underlying database engine.
.SS "create_database"
.IX Subsection "create_database"
.Vb 1
\&    $driver\->create_database( $name );
.Ve
.PP
Create the database for the corresponding \s-1DBD\s0 driver.
.PP
Return a Test::Database::Handle in case of success, and nothing in
case of failure to create the database.
.ie n .SS "drop_database( $name )"
.el .SS "drop_database( \f(CW$name\fP )"
.IX Subsection "drop_database( $name )"
.Vb 1
\&    $driver\->drop_database( $name );
.Ve
.PP
Drop the database named \f(CW$name\fR.
.SH "OVERRIDABLE METHODS WHEN WRITING A DRIVER"
.IX Header "OVERRIDABLE METHODS WHEN WRITING A DRIVER"
Some methods have defaults implementations in Test::Database::Driver,
but those can be overridden in the derived class:
.SS "is_filebased"
.IX Subsection "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.
.SS "databases"
.IX Subsection "databases"
.Vb 1
\&    my @db = $driver\->databases();
.Ve
.PP
Return the names of all existing databases for this driver as a list
(the default implementation is only valid for file-based drivers).
.SH "TEMPORARY STORAGE ORGANIZATION"
.IX Header "TEMPORARY STORAGE ORGANIZATION"
Subclasses of Test::Database::Driver store useful information
in the system's temporary directory, under a directory named
\&\fITest\-Database\-$user\fR (\f(CW$user\fR being the current user's name).
.PP
That directory contains the following files:
.IP "database files" 4
.IX Item "database files"
The database files and directories created by file-based drivers
controlled by Test::Database are stored here, under names matching
\&\fItdd_\f(BI\s-1DRIVER\s0\fI_\f(BIN\fI\fR, where \fB\s-1DRIVER\s0\fR is the lowercased name of the
driver and \fBN\fR is a number.
.IP "the \fImapping.yml\fR file" 4
.IX Item "the mapping.yml file"
A \s-1YAML\s0 file containing a \f(CW\*(C`cwd()\*(C'\fR / database name mapping, to enable a
given test suite to receive the same database handles in all the test
scripts that call the \f(CW\*(C`Test::Database\->handles()\*(C'\fR method.
.SH "AUTHOR"
.IX Header "AUTHOR"
Philippe Bruhat (BooK), \f(CW\*(C`<book@cpan.org>\*(C'\fR
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2010 Philippe Bruhat (BooK), all rights reserved.
.SH "LICENSE"
.IX Header "LICENSE"
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.