Temp.hs

{-|
This module provides functions for creating a temporary @postgres@ instance.
By default it will create a temporary data directory and
a temporary directory for a UNIX domain socket for @postgres@ to listen on.

Here is an example using the expection safe 'with' function:

 @
 'with' $ \\db -> 'Control.Exception.bracket'
    ('PG.connectPostgreSQL' ('toConnectionString' db))
    'PG.close' $
    \\conn -> 'PG.execute_' conn "CREATE TABLE foo (id int)"
 @

To extend or override the defaults use `withConfig` (or `startConfig`).

@tmp-postgres@ ultimately calls (optionally) @initdb@, @postgres@ and
(optionally) @createdb@.

All of the command line, environment variables and configuration files
that are generated by default for the respective executables can be
extended.

In general @tmp-postgres@ is useful if you want a clean temporary
@postgres@ and do not want to worry about clashing with an existing
postgres instance (or needing to ensure @postgres@ is already running).

Here are some different use cases for @tmp-postgres@ and their respective
configurations:

* The default 'with' and 'start' functions can be used to make a sandboxed
temporary database for testing.
* By disabling @initdb@ one could run a temporary
isolated postgres on a base backup to test a migration.
* By using the 'stopPostgres' and 'withRestart' functions one can test
backup strategies.

WARNING!!
Ubuntu's PostgreSQL installation does not put @initdb@ on the @PATH@. We need to add it manually.
The necessary binaries are in the @\/usr\/lib\/postgresql\/VERSION\/bin\/@ directory, and should be added to the @PATH@

 > echo "export PATH=$PATH:/usr/lib/postgresql/VERSION/bin/" >> /home/ubuntu/.bashrc

-}

module Database.Postgres.Temp
  (
  -- * Exception safe interface
    with
  , withConfig
  -- * Separate start and stop interface.
  , start
  , startConfig
  , stop
  , defaultConfig
  , defaultPostgresConf
  , standardProcessConfig
  -- ** Custom Config builder helpers
  , optionsToDefaultConfig
  -- * Starting and Stopping postgres without removing the temporary directory
  , restart
  , stopPostgres
  , withRestart
  -- * Reloading the config
  , reloadConfig
  -- * Main resource handle
  , DB
  -- ** 'DB' manipulation
  , prettyPrintDB
  , toConnectionString
  , toConnectionOptions
  , toDataDirectory
  , makeDataDirPermanent
  -- * Monoidial Configuration Types
  -- ** 'Config'
  , Config (..)
  , prettyPrintConfig
    -- *** 'Config' Lenses
  , configPlanL
  , configSocketL
  , configDataDirL
  , configPortL
  -- ** 'PartialPlan'
  , PartialPlan (..)
  -- *** 'PartialPlan' lenses
  , partialPlanConfigL
  , partialPlanCreateDbL
  , partialPlanDataDirectoryL
  , partialPlanInitDbL
  , partialPlanLoggerL
  , partialPlanPostgresL
  -- ** 'PartialPostgresPlan'
  , PartialPostgresPlan (..)
  -- *** 'PartialPostgresPlan' lenses
  , partialPostgresPlanClientConfigL
  , partialPostgresPlanProcessConfigL
  -- ** 'PartialProcessConfig'
  , PartialProcessConfig (..)
  -- *** 'PartialProcessConfig' Lenses
  , partialProcessConfigCmdLineL
  , partialProcessConfigEnvVarsL
  , partialProcessConfigStdErrL
  , partialProcessConfigStdInL
  , partialProcessConfigStdOutL
  -- ** 'PartialEnvVars'
  , PartialEnvVars (..)
  -- *** 'PartialEnvVars' Lenses
  , partialEnvVarsInheritL
  , partialEnvVarsSpecificL
  -- ** 'PartialCommandLineArgs'
  , PartialCommandLineArgs (..)
  -- *** 'PartialCommandLineArgs' Lenses
  , partialCommandLineArgsIndexBasedL
  , partialCommandLineArgsKeyBasedL
  -- ** 'PartialDirectoryType'
  , PartialDirectoryType (..)
  -- ** 'PartialSocketClass'
  , PartialSocketClass (..)
  -- ** 'Logger'
  , Logger
  -- * Internal events passed to the 'partialPlanLogger' .
  , Event (..)
    -- * Errors
  , StartError (..)
  ) where
import Database.Postgres.Temp.Internal
import Database.Postgres.Temp.Internal.Core
import Database.Postgres.Temp.Internal.Partial