File Coverage

blib/lib/Test/DB.pm

Criterion	Covered	Total	%
statement	11	41	26.8
branch	0	12	0.0
condition	0	2	0.0
subroutine	4	12	33.3
pod	7	8	87.5
total	22	75	29.3

package Test::DB;

use 5.014;

use strict;
use warnings;

use Venus::Class;

# VERSION

our $VERSION = '0.10';

# AUTHORITY

our $AUTHORITY = 'cpan:AWNCORP';

# METHODS

sub build {
  my ($self, %options) = @_;

  my $type = $self->type($options{database});

  if (lc($type) eq 'sqlite') {
    return $self->sqlite(%options);
  }
  elsif (lc($type) eq 'postgres') {
    return $self->postgres(%options);
  }
  elsif (lc($type) eq 'mysql') {
    return $self->mysql(%options);
  }
  elsif (lc($type) eq 'mssql') {
    return $self->mssql(%options);
  }
  else {
    return undef;
  }
}

sub create {
  my ($self, %options) = @_;

  if (my $driver = $self->build(%options)) {
    return $driver->create;
  }
  else {
    return undef;
  }
}

sub clone {
  my ($self, %options) = @_;

  if (my $driver = $self->build(%options)) {
    return $driver->clone;
  }
  else {
    return undef;
  }
}

sub mssql {
  my ($self, %options) = @_;

  require Test::DB::Mssql;

  return Test::DB::Mssql->new(%options);
}

sub mysql {
  my ($self, %options) = @_;

  require Test::DB::Mysql;

  return Test::DB::Mysql->new(%options);
}

sub postgres {
  my ($self, %options) = @_;

  require Test::DB::Postgres;

  return Test::DB::Postgres->new(%options);
}

sub sqlite {
  my ($self, %options) = @_;

  require Test::DB::Sqlite;

  return Test::DB::Sqlite->new(%options);
}

sub type {
  my ($self, $name) = @_;

  return $name || $ENV{TESTDB_DATABASE} || 'sqlite';
}

1;



=head1 NAME

Test::DB - Temporary Testing Databases

=cut

=head1 ABSTRACT

Temporary Databases for Testing

=cut

=head1 VERSION

0.10

=cut

=head1 SYNOPSIS

  use Test::DB;

  my $tdb = Test::DB->new;

  # my $tdbo = $tdb->create(database => 'sqlite');

  # my $dbh = $tdbo->dbh;

=cut

=head1 DESCRIPTION

This package provides a framework for setting up and tearing down temporary
databases for testing purposes. This framework requires a user (optionally with
password) which has the ability to create new databases and works by creating
test-specific databases owned by the user specified. B Test databases
are not automatically destroyed and should be cleaned up manually by call the
C method on the database-specific test database object.

=head2 process

B

=over 4

=item #1

Establish a connection to the DB using some "initial" database.

  my $tdbo = $tdb->postgres(initial => 'template0');

=item #2

Using the established connection, create the test/temporary database.

  $tdbo->create;

=item #3

Establish a connection to the newly created test/temporary database.

  $tdbo->create->dbh;

=back

B

=over 4

=item #1

Establish a connection to the DB using the "initial" database.

  # using the created test/temporary database object

=item #2

Using the established connection, drop the test/temporary database.

  $tdbo->destroy;

=back

=head2 usages

B

=over 4

=item #1

  my $tdb = Test::DB->new;
  my $dbh = $tdb->sqlite(%options)->dbh;

=back

B

=over 4

=item #1

  my $tdb = Test::DB->new;
  my $tdbo = $tdb->postgres(%options)->create;
  my $schema = DBIx::Class::Schema->connect(
    dsn => $tdbo->dsn,
    username => $tdbo->username,
    password => $tdbo->password,
  );

=back

B

=over 4

=item #1

  my $tdb = Test::DB->new;
  my $tdbo = $tdb->mysql(%options)->create;
  my $mysql = Mojo::mysql->new($tdbo->uri);

=back

B

=over 4

=item #1

  my $tdb = Test::DB->new;
  my $tdbo = $tdb->postgres(%options)->create;
  my $postgres = Mojo::Pg->new($tdbo->uri);

=back

B

=over 4

=item #1

  my $tdb = Test::DB->new;
  my $tdbo = $tdb->postgres(%options)->clone('template0');
  my $postgres = Mojo::Pg->new($tdbo->uri);

=back

B

=over 4

=item #1

  my $tdb = Test::DB->new;
  my $tdbo = $tdb->sqlite(%options)->create;
  my $sqlite = Mojo::SQLite->new($tdbo->uri);

=back

=cut

=head1 METHODS

This package provides the following methods:

=cut

=head2 clone

clone(Str :$database, Str %options) : Maybe[Object]

The clone method generates a database based on the type and database template
specified and returns a driver object with an active connection, C and
C. If the database specified doesn't have a corresponding database driver
this method will returned the undefined value. The type of database can be
omitted if the C environment variable is set, if not the type
of database must be either C, C, C or C.  Any
options provided are passed along to the test database object class
constructor.

=over 4

=item clone example 1

  # given: synopsis

  $ENV{TESTDB_DATABASE} = 'postgres';

  $tdb->clone(template => 'template0');

=back

=over 4

=item clone example 2

  # given: synopsis

  $ENV{TESTDB_DATABASE} = 'postgres';
  $ENV{TESTDB_TEMPLATE} = 'template0';

  $tdb->clone;

=back

=over 4

=item clone example 3

  # given: synopsis

  $ENV{TESTDB_TEMPLATE} = 'template0';

  $tdb->clone(database => 'postgres');

=back

=cut

=head2 create

create(Str :$database, Str %options) : Maybe[Object]

The create method generates a database based on the type specified and returns
a driver object with an active connection, C and C. If the database
specified doesn't have a corresponding database driver this method will
returned the undefined value. The type of database can be omitted if the
C environment variable is set, if not the type of database
must be either C, C, C or C. Any options
provided are passed along to the test database object class constructor.

=over 4

=item create example 1

  # given: synopsis

  $tdb->create;

=back

=over 4

=item create example 2

  # given: synopsis

  $ENV{TESTDB_DATABASE} = 'sqlite';

  $tdb->create;

=back

=over 4

=item create example 3

  # given: synopsis

  $tdb->create(database => 'sqlite');

=back

=cut

=head2 mssql

mssql(Str %options) : Maybe[InstanceOf["Test::DB::Mssql"]]

The mssql method builds and returns a L object.

=over 4

=item mssql example 1

  # given: synopsis

  $tdb->mssql;

=back

=cut

=head2 mysql

mysql(Str %options) : Maybe[InstanceOf["Test::DB::Mysql"]]

The mysql method builds and returns a L object.

=over 4

=item mysql example 1

  # given: synopsis

  $tdb->mysql;

=back

=cut

=head2 postgres

postgres(Str %options) : Maybe[InstanceOf["Test::DB::Postgres"]]

The postgres method builds and returns a L object.

=over 4

=item postgres example 1

  # given: synopsis

  $tdb->postgres;

=back

=cut

=head2 sqlite

sqlite(Str %options) : Maybe[InstanceOf["Test::DB::Sqlite"]]

The sqlite method builds and returns a L object.

=over 4

=item sqlite example 1

  # given: synopsis

  $tdb->sqlite;

=back

=cut