NAME
    DBIx::TempDB - Create a temporary database

VERSION
    0.07

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

      # create a temp database
      my $tmpdb = DBIx::TempDB->new("postgresql://postgres@localhost");

      # 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 <https://github.com/jhthorsen/dbix-tempdb/issues>
    or pull request for more backend support.

    This module is currently EXPERIMENTAL. That means that if any major
    design flaws have been made, they will be fixed without warning.

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
      $self = $self->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.

  dsn
      ($dsn, $user, $pass, $attrs) = $self->dsn;
      ($dsn, $user, $pass, $attrs) = DBIx::TempDB->dsn($url);

    Will parse "url" or $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. You can on the other hand call it as a
    class method, with a URI::db or URL string as input.

  execute
      $self = $self->execute($sql);

    This method will execute the given $sql statements in the temporary SQL
    server.

  execute_file
      $self = $self->execute_file("relative/to/executable.sql");
      $self = $self->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
      $self = DBIx::TempDB->new($url, %args);
      $self = DBIx::TempDB->new("mysql://127.0.0.1");
      $self = DBIx::TempDB->new("postgresql://postgres@db.example.com");
      $self = 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" 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.

        TODO: "drop_from_child=1" might become the default.

        "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 <http://easyconnect.no>, Knut Arne Bjørndal.

    *   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 = $self->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"