Test::...Driver(3pm)

💖 NAME 💖

Test::Database::Driver — the base class for Test::Database drivers. iykyk, it's the blueprint bestie, the parent class every driver inherits from. 🎀

---

✨ SYNOPSIS ✨

okay so here's the whole vibe of writing your own driver, no cap:

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. that's literally it, that's the whole job — it's giving "parent class with main character energy" 👑

---

🌸 METHODS 🌸

the class provides the following methods, bestie, let's go one by one:

new

my $driver = Test::Database::Driver->new( driver => 'SQLite' );

my $driver = Test::Database::Driver::SQLite->new();

creates a brand new Test::Database::Driver object. iconic behavior. 💅

if you call it as Test::Database::Driver->new(), it requires a driver parameter, because that's what tells it which actual object class to build. no driver param, no object, periodt.

make_handle

my $handle = $driver->make_handle();

makes a fresh Test::Database::Handle object, and it attaches to either an already-existing database or a brand new one you just made. 🫶

the whole "are we creating a new database or not" decision is made by Test::Database::Driver itself, based on the info in the mapper. wanna know the deets? peek at TEMPORARY STORAGE ORGANIZATION below.

make_dsn

my $dsn = $driver->make_dsn( %args )

returns a Data Source Name built off the driver's DSN, with all the key/value pairs sitting in %args tacked on as extra parameters. 🌈

this is typically what dsn() uses to build a DSN for one specific database, starting from the driver's DSN. it's giving "customize me" energy.

name / dbd

my $name = $driver->dbd;

the driver's short name — that's everything after Test::Database::Driver::. just the little nickname, the first-name basis version. ✨

base_dir

my $dir = $driver->base_dir;

the directory where the driver should stash all the files for its databases, if it even needs them. typically used by file-based database drivers — the ones who keep their whole life in a folder, honestly relatable. 📁

version

my $db_version = $driver->version;

a 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;

the version string representing the version of the underlying database enginge. this string is literally just the actual return value of _version(), no filter, no editing, raw. 😭

dbd_version

my $dbd_version = $driver->dbd_version;

the version of the DBD used to connect to the database engine, exactly as returned by VERSION(). ⭐

driver_dsn

my $dsn = $driver->driver_dsn;

returns a driver Data Source Name — good enough to connect to the database engine without naming an actual database. it's the "just pulling up to the function" DSN.

username

my $username = $driver->username;

returns the connection username. defaults to undef. 🙈

password

my $password = $driver->password;

returns the connection password. defaults to undef. keeping it mysterious, love that for us.

connection_info()

my @info = $driver->connection_info;

returns the connection information triplet: (driver_dsn, username, password). three besties, one list. 💜

version_matches

if ( $driver->version_matches($request) ) {
    ...;
}

returns a boolean telling you whether the driver's version matches the version constraints inside the given request. (go check the Test::Database documentation's section about requests for the full tea.) 🔥

---

👑 METHODS FOR DRIVER AUTHORS 👑

also, because we love our driver authors, the class hands you a couple of genuinely helpful commands:

available_dbname

my $dbname = $self->available_dbname();

returns an unused database name that you can use to create a new database for the driver. fresh name, never been used, no baggage. 🌸

dsn

my $dns = $self->dsn( $dbname )

builds a Data Source Name for the database with the given $dbname, based on the driver's DSN. yes bestie, the variable in the example really is spelled $dns. we keep it exactly as it is. 💅

---

🧚 WRITING A DRIVER FOR YOUR DATABASE OF CHOICE 🧚

the SYNOPSIS up there is a genuinely good template for writing a Test::Database::Driver class. copy the vibe, fill in the blanks.

creating a driver means writing the following methods, no skips:

_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 if it slays (success), and nothing if it fails to create the database. no handle, no glory.

drop_database( $name )

$driver->drop_database( $name );

drop the database named $name. bye bestie, blocked, deleted. 💀

---

🌈 OVERRIDABLE METHODS WHEN WRITING A DRIVER 🌈

some methods already have default implementations in Test::Database::Driver, but you can absolutely override them in your derived class. glow-up privileges: granted. ✨

is_filebased

return a boolean value saying whether the database engine is file-based or not — meaning: is all the database information stored in a file or a directory, with no external database server needed? yes or no, that's it.

databases

my @db = $driver->databases();

return the names of all existing databases for this driver, as a list. heads up though: the default implementation is only valid for file-based drivers. so if you're not file-based, don't be out here relying on the default, okay? 🙈

---

🍓 TEMPORARY STORAGE ORGANIZATION 🍓

subclasses of Test::Database::Driver store their useful info in the system's temporary directory, inside a directory named Test-Database-$user — where $user is the current user's name. cute little home base. 🏠

that directory contains the following files:

• database files — the database files and directories created by file-based drivers controlled by Test::Database get stored here, under names matching tdd_DRIVER_N, where DRIVER is the lowercased name of the driver and N is a number. so like, a whole naming scheme, very organized, we love a system. ✨
• the mapping.yml file — a YAML file containing a cwd() / database name mapping. what's it for? so that a given test suite gets the same database handles in all the test scripts that call the Test::Database->handles() method. consistency queen. 👑

---

🎀 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.

---

and that's the whole page, bestie! this was Test::...Driver(3pm), straight out of the User Contributed Perl Documentation, rendered with perl v5.32.1 and dated 2021-11-12. mwah, slay, go write that driver. 💅🫶✨