NAME

DBIx::TempDB - Create a temporary database

VERSION

0.16

SYNOPSIS

  use Test::More;
  use DBIx::TempDB;
  use DBI;

  # provide credentials with environment variables
  plan skip_all => 'TEST_PG_DSN=postgresql://postgres@localhost' unless $ENV{TEST_PG_DSN};

  # create a temp database
  my $tmpdb = DBIx::TempDB->new($ENV{TEST_PG_DSN});

  # print complete url to db server with database name
  diag $tmpdb->url;

  # useful for reading in fixtures
  $tmpdb->execute("create table users (name text)");
  $tmpdb->execute_file("path/to/file.sql");

  # connect to the temp database
  my $db = DBI->connect($tmpdb->dsn);

  # run tests...

  done_testing;
  # database is cleaned up when test exit

DESCRIPTION

DBIx::TempDB is a module which allows you to create a temporary database, which only lives as long as your process is alive. This can be very convenient when you want to run tests in parallel, without messing up the state between tests.

This module currently support PostgreSQL, MySQL and SQLite by installing the optional DBD::Pg, DBD::mysql and/or DBD::SQLite modules.

Please create an issue or pull request for more backend support.

CAVEAT

Creating a database is easy, but making sure it gets clean up when your process exit is a totally different ball game. This means that DBIx::TempDB might fill up your server with random databases, unless you choose the right "drop strategy". Have a look at the "drop_from_child" parameter you can give to "new" and test the different values and select the one that works for you.

ENVIRONMENT VARIABLES

DBIX_TEMP_DB_KEEP_DATABASE

Setting this variable will disable the core feature in this module: A unique database will be created, but it will not get dropped/deleted.

DBIX_TEMP_DB_URL

This variable is set by "create_database" and contains the complete URL pointing to the temporary database.

Note that calling "create_database" on different instances of DBIx::TempDB will overwrite DBIX_TEMP_DB_URL.

METHODS

create_database

  $tmpdb = $tmpdb->create_database;

This method will create a temp database for the current process. Calling this method multiple times will simply do nothing. This method is normally automatically called by "new".

The database name generate is defined by the "template" parameter passed to "new", but normalization will be done to make it work for the given database.

drop_databases

  $tmpdb->drop_databases;
  $tmpdb->drop_databases({tmpdb => "include"});
  $tmpdb->drop_databases({tmpdb => "only"});
  $tmpdb->drop_databases({name => "some_database_name"});

Used to drop either sibling databases (default), sibling databases and the current database or a given database by name.

dsn

  ($dsn, $user, $pass, $attrs) = $tmpdb->dsn;

Will parse "url" and return a list of arguments suitable for "connect" in DBI.

Note that this method cannot be called as an object method before "create_database" is called.

See also "dsn_for" in DBIx::TempDB::Util.

execute

  $tmpdb = $tmpdb->execute(@sql);

This method will execute a list of @sql statements in the temporary SQL server.

execute_file

  $tmpdb = $tmpdb->execute_file("relative/to/executable.sql");
  $tmpdb = $tmpdb->execute_file("/absolute/path/stmt.sql");

This method will read the contents of a file and execute the SQL statements in the temporary server.

This method is a thin wrapper around "execute".

new

  $tmpdb = DBIx::TempDB->new($url, %args);
  $tmpdb = DBIx::TempDB->new("mysql://127.0.0.1");
  $tmpdb = DBIx::TempDB->new("postgresql://postgres@db.example.com");
  $tmpdb = DBIx::TempDB->new("sqlite:");

Creates a new object after checking the $url is valid. %args can be:

• auto_create

  "create_database" will be called automatically, unless auto_create is set to a false value.

• drop_from_child

  Setting "drop_from_child" to a true value will create a child process which will remove the temporary database, when the main process ends. There are two possible values:

  drop_from_child=1 (the default) will create a child process which monitor the DBIx::TempDB object with a pipe. This will then DROP the temp database if the object goes out of scope or if the process ends.

  drop_from_child=2 will create a child process detached from the parent, which monitor the parent with kill(0, $parent).

  The double fork code is based on a paste contributed by Easy Connect AS, Knut Arne Bjørndal.

  See also "on_process_end" in DBIx::TempDB::Util.

• template

  Customize the generated database name. Default template is "tmp_%U_%X_%H%i". Possible variables to expand are:

    %i = The number of tries if tries are higher than 0. Example: "_3"
    %H = Hostname
    %P = Process ID ($$)
    %T = Process start time ($^T)
    %U = UID of current user
    %X = Basename of executable

  The default is subject to change!

url

  $url = $tmpdb->url;

Returns the input URL as URI::db compatible object. This URL will have the dbname part set to the database from "create_database", but not until after "create_database" is actually called.

The URL returned can be passed directly to modules such as Mojo::Pg and Mojo::mysql.

COPYRIGHT AND LICENSE

Copyright (C) 2015, Jan Henning Thorsen

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

AUTHOR

Jan Henning Thorsen - jhthorsen@cpan.org

cpanm DBIx::TempDB

perl -MCPAN -e shell
install DBIx::TempDB