diff options
Diffstat (limited to 'lib/Test/Database/Driver.pm')
| -rw-r--r-- | lib/Test/Database/Driver.pm | 123 |
1 files changed, 76 insertions, 47 deletions
diff --git a/lib/Test/Database/Driver.pm b/lib/Test/Database/Driver.pm index 4a4a3a5..8bfa9d3 100644 --- a/lib/Test/Database/Driver.pm +++ b/lib/Test/Database/Driver.pm @@ -1,4 +1,5 @@ package Test::Database::Driver; +$Test::Database::Driver::VERSION = '1.112'; use strict; use warnings; use Carp; @@ -58,8 +59,6 @@ sub new { } my $self = bless { - username => '', - password => '', %args, dbd => $class->name() || $args{dbd}, }, @@ -339,32 +338,38 @@ Test::Database::Driver - Base class for Test::Database drivers =head1 DESCRIPTION -C<Test::Database::Driver> is a base class for creating C<Test::Database> +Test::Database::Driver is a base class for creating L<Test::Database> drivers. =head1 METHODS The class provides the following methods: -=over 4 +=head2 new + + my $driver = Test::Database::Driver->new( driver => 'SQLite' ); -=item new( %args ) + my $driver = Test::Database::Driver::SQLite->new(); -Create a new C<Test::Database::Driver> object. +Create a new Test::Database::Driver object. If called as C<< Test::Database::Driver->new() >>, requires a C<driver> parameter to define the actual object class. -=item make_handle() +=head2 make_handle -Create a new C<Test::Database::Handle> object, attached to an existing database + my $handle = $driver->make_handle(); + +Create a new L<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 -C<Test::Database::Driver> based on the information in the mapper. +Test::Database::Driver based on the information in the mapper. See L<TEMPORARY STORAGE ORGANIZATION> for details. -=item make_dsn( %args ) +=head2 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 C<%args> as additional parameters. @@ -372,122 +377,146 @@ pairs contained in C<%args> as additional parameters. This is typically used by C<dsn()> to make a DSN for a specific database, based on the driver's DSN. -=item name() +=head2 name -=item dbd() +=head2 dbd + + my $name = $driver->dbd; The driver's short name (everything after C<Test::Database::Driver::>). -=item base_dir() +=head2 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. -=item version() +=head2 version + + my $db_version = $driver->version; C<version> object representing the version of the underlying database enginge. This object is build with the return value of C<_version()>. -=item version_string() +=head2 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 C<_version()>. -=item dbd_version() +=head2 dbd_version + + my $dbd_version = $driver->dbd_version; The version of the DBD used to connect to the database engine, as returned by C<VERSION()>. -=item driver_dsn() +=head2 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. -=item username() +=head2 username + + my $username = $driver->username; + +Return the connection username. Defaults to C<undef>. -Return the connection username. +=head2 password -=item password() + my $password = $driver->password; -Return the connection password. +Return the connection password. Defaults to C<undef>. -=item connection_info() +=head2 connection_info() + + my @info = $driver->connection_info; Return the connection information triplet (C<driver_dsn>, C<username>, C<password>). -=item version_matches( $request ) +=head2 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 L<Test::Database> documentation's section about requests). -=back +=head1 METHODS FOR DRIVER AUTHORS The class also provides a few helpful commands that may be useful for driver authors: -=over 4 +=head2 available_dbname -=item available_dbname() + my $dbname = $self->available_dbname(); Return an unused database name that can be used to create a new database for the driver. -=item dsn( $dbname ) +=head2 dsn -Build a Data Source Name for the database with the given C<$dbname>, -based on the driver's DSN. + my $dns = $self->dsn( $dbname ) -=back +Build a Data Source Name for the database with the given C<$dbname>, +based on the driver's DSN. =head1 WRITING A DRIVER FOR YOUR DATABASE OF CHOICE The L<SYNOPSIS> contains a good template for writing a -C<Test::Database::Driver> class. +Test::Database::Driver class. Creating a driver requires writing the following methods: -=over 4 +=head2 _version -=item _version() + my $version = $driver->_version; Return the version of the underlying database engine. -=item create_database( $name ) +=head2 create_database + + $driver->create_database( $name ); Create the database for the corresponding DBD driver. -Return a C<Test::Database::Handle> in case of success, and nothing in +Return a L<Test::Database::Handle> in case of success, and nothing in case of failure to create the database. -=item drop_database( $name ) +=head2 drop_database( $name ) + + $driver->drop_database( $name ); Drop the database named C<$name>. -=back +=head1 OVERRIDABLE METHODS WHEN WRITING A DRIVER -Some methods have defaults implementations in C<Test::Database::Driver>, +Some methods have defaults implementations in Test::Database::Driver, but those can be overridden in the derived class: -=over 4 - -=item is_filebased() +=head2 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. -=item databases() +=head2 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). -=back - =head1 TEMPORARY STORAGE ORGANIZATION -Subclasses of C<Test::Database::Driver> store useful information +Subclasses of Test::Database::Driver store useful information in the system's temporary directory, under a directory named F<Test-Database-$user> (C<$user> being the current user's name). @@ -498,7 +527,7 @@ That directory contains the following files: =item database files The database files and directories created by file-based drivers -controlled by C<Test::Database> are stored here, under names matching +controlled by L<Test::Database> are stored here, under names matching F<tdd_B<DRIVER>_B<N>>, where B<DRIVER> is the lowercased name of the driver and B<N> is a number. @@ -506,7 +535,7 @@ driver and B<N> is a number. A YAML file containing a C<cwd()> / database name mapping, to enable a given test suite to receive the same database handles in all the test -scripts that call the C<Test::Database->handles()> method. +scripts that call the C<< Test::Database->handles() >> method. =back |