-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Start and stop a temporary postgres
--   
--   Start and stop a temporary postgres. See README.md
@package tmp-postgres
@version 1.32.0.0


-- | This module provides the low level functionality for running
--   <tt>initdb</tt>, <tt>postgres</tt> and <tt>createdb</tt> to make a
--   database.
--   
--   See <a>startPlan</a> for more details.
module Database.Postgres.Temp.Internal.Core

-- | Internal events for debugging
data Event

-- | The first event. This useful for debugging what is actual passed to
--   the <tt>initdb</tt>, <tt>createdb</tt> and <tt>postgres</tt>.
StartPlan :: String -> Event

-- | The second event. Postgres is about to get called
StartPostgres :: Event

-- | The third event. Postgres started. We are now about to setup a
--   reconnect loop (racing with a process checker)
WaitForDB :: Event

-- | The fourth event and (possibly all subsequent events). We are looping
--   trying to successfully connect to the <tt>postgres</tt> process.
TryToConnect :: Event

-- | A list of failures that can occur when starting. This is not and
--   exhaustive list but covers the errors that the system catches for the
--   user.
data StartError

-- | <tt>postgres</tt> failed before a connection succeeded. Most likely
--   this is due to invalid configuration
StartPostgresFailed :: ExitCode -> StartError

-- | <tt>initdb</tt> failed. This can be from invalid configuration or
--   using a non-empty data directory
InitDbFailed :: String -> String -> ExitCode -> StartError
[startErrorStdOut] :: StartError -> String
[startErrorStdErr] :: StartError -> String
[startErrorExitCode] :: StartError -> ExitCode

-- | <tt>createdb</tt> failed. This can be from invalid configuration or
--   the database might already exist.
CreateDbFailed :: String -> String -> ExitCode -> StartError
[startErrorStdOut] :: StartError -> String
[startErrorStdErr] :: StartError -> String
[startErrorExitCode] :: StartError -> ExitCode

-- | The <a>Plan</a> was missing info and a complete <a>Plan</a> could not
--   be created.
PlanFailed :: String -> [String] -> StartError

-- | The <a>ProcessConfig</a> was missing info and a
--   <a>CompleteProcessConfig</a> could not be created.
CompleteProcessConfigFailed :: String -> [String] -> StartError

-- | Timed out waiting for <tt>postgres</tt> to accept a connection
ConnectionTimedOut :: StartError
DeleteDbError :: SqlError -> StartError

-- | This will happen if a <a>Plan</a> is missing a <a>initDbConfig</a>.
EmptyDataDirectory :: StartError

-- | This is called if copying a folder cache fails.
CopyCachedInitDbFailed :: String -> ExitCode -> StartError

-- | Failed to find a data directory when trying to get a cached
--   <tt>initdb</tt> folder.
FailedToFindDataDirectory :: String -> StartError

-- | We tried to copy a data directory to a snapshot folder and it failed
SnapshotCopyFailed :: String -> ExitCode -> StartError

-- | A way to log internal <a>Event</a>s
type Logger = Event -> IO ()

-- | <tt>postgres</tt> is not ready until we are able to successfully
--   connect. <a>waitForDB</a> attempts to connect over and over again and
--   returns after the first successful connection.
waitForDB :: Logger -> Options -> IO ()

-- | <a>CompleteProcessConfig</a> contains the configuration necessary for
--   starting a process. It is essentially a stripped down
--   <a>CreateProcess</a>.
data CompleteProcessConfig
CompleteProcessConfig :: [(String, String)] -> [String] -> Handle -> Handle -> Handle -> CompleteProcessConfig

-- | Environment variables
[completeProcessConfigEnvVars] :: CompleteProcessConfig -> [(String, String)]

-- | Command line arguements
[completeProcessConfigCmdLine] :: CompleteProcessConfig -> [String]

-- | The <a>Handle</a> for standard input
[completeProcessConfigStdIn] :: CompleteProcessConfig -> Handle

-- | The <a>Handle</a> for standard output
[completeProcessConfigStdOut] :: CompleteProcessConfig -> Handle

-- | The <a>Handle</a> for standard error
[completeProcessConfigStdErr] :: CompleteProcessConfig -> Handle

-- | Start a process interactively and return the <a>ProcessHandle</a>
startProcess :: String -> CompleteProcessConfig -> IO ProcessHandle

-- | Stop a <a>ProcessHandle</a>. An alias for <a>waitForProcess</a>
stopProcess :: ProcessHandle -> IO ExitCode

-- | Start a process and block until it finishes return the
--   <a>ExitCode</a>.
executeProcess :: String -> CompleteProcessConfig -> IO ExitCode

-- | Start a process and block until it finishes return the <a>ExitCode</a>
--   and the stderr output.
executeProcessAndTee :: String -> CompleteProcessConfig -> IO (ExitCode, String, String)

-- | <a>CompletePostgresPlan</a> is used be <a>startPostgresProcess</a> to
--   start the <tt>postgres</tt> and then attempt to connect to it.
data CompletePostgresPlan
CompletePostgresPlan :: CompleteProcessConfig -> Options -> CompletePostgresPlan

-- | The process config for <tt>postgres</tt>
[completePostgresPlanProcessConfig] :: CompletePostgresPlan -> CompleteProcessConfig

-- | Connection options. Used to verify that <tt>postgres</tt> is ready.
[completePostgresPlanClientOptions] :: CompletePostgresPlan -> Options

-- | The output of calling <a>startPostgresProcess</a>.
data PostgresProcess
PostgresProcess :: Options -> ProcessHandle -> PostgresProcess

-- | Connection options
[postgresProcessClientOptions] :: PostgresProcess -> Options

-- | <tt>postgres</tt> process handle
[postgresProcessHandle] :: PostgresProcess -> ProcessHandle

-- | Stop the <tt>postgres</tt> process after attempting to terminate all
--   the connections.
stopPostgresProcess :: Bool -> PostgresProcess -> IO ExitCode

-- | Start the <tt>postgres</tt> process and block until a successful
--   connection occurs. A separate thread we continously check to see if
--   the <tt>postgres</tt> process has crashed.
startPostgresProcess :: Int -> Logger -> CompletePostgresPlan -> IO PostgresProcess

-- | Call <tt>createdb</tt> and tee the output to return if there is an an
--   exception. Throws <a>CreateDbFailed</a>.
executeCreateDb :: CompleteProcessConfig -> IO ()

-- | <a>Plan</a> is the low level configuration necessary for initializing
--   a database cluster starting <tt>postgres</tt> and creating a database.
--   There is no validation done on the <a>Plan</a>. It is recommend that
--   one use the higher level functions such as <a>start</a> which will
--   generate plans that are valid. <a>Plan</a>s are used internally but
--   are exposed if the higher level plan generation is not sufficent.
data Plan
Plan :: Logger -> Maybe CompleteProcessConfig -> Maybe CompleteCopyDirectoryCommand -> Maybe CompleteProcessConfig -> CompletePostgresPlan -> String -> FilePath -> Int -> Plan
[completePlanLogger] :: Plan -> Logger
[completePlanInitDb] :: Plan -> Maybe CompleteProcessConfig
[completePlanCopy] :: Plan -> Maybe CompleteCopyDirectoryCommand
[completePlanCreateDb] :: Plan -> Maybe CompleteProcessConfig
[completePlanPostgres] :: Plan -> CompletePostgresPlan
[completePlanConfig] :: Plan -> String
[completePlanDataDirectory] :: Plan -> FilePath
[completePlanConnectionTimeout] :: Plan -> Int

-- | <a>startPlan</a> optionally calls <tt>initdb</tt>, optionally calls
--   <tt>createdb</tt> and unconditionally calls <tt>postgres</tt>.
--   Additionally it writes a "postgresql.conf" and does not return until
--   the <tt>postgres</tt> process is ready. See
--   <a>startPostgresProcess</a> for more details.
startPlan :: Plan -> IO PostgresProcess

-- | Stop the <tt>postgres</tt> process. See <a>stopPostgresProcess</a> for
--   more details.
stopPlan :: PostgresProcess -> IO ExitCode
instance GHC.Classes.Ord Database.Postgres.Temp.Internal.Core.CompleteCopyDirectoryCommand
instance GHC.Classes.Eq Database.Postgres.Temp.Internal.Core.CompleteCopyDirectoryCommand
instance GHC.Show.Show Database.Postgres.Temp.Internal.Core.CompleteCopyDirectoryCommand
instance GHC.Classes.Eq Database.Postgres.Temp.Internal.Core.StartError
instance GHC.Show.Show Database.Postgres.Temp.Internal.Core.StartError
instance GHC.Classes.Ord Database.Postgres.Temp.Internal.Core.Event
instance GHC.Classes.Eq Database.Postgres.Temp.Internal.Core.Event
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Core.Plan
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Core.CompleteCopyDirectoryCommand
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Core.PostgresProcess
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Core.CompletePostgresPlan
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Core.CompleteProcessConfig
instance GHC.Exception.Type.Exception Database.Postgres.Temp.Internal.Core.StartError
instance GHC.Show.Show Database.Postgres.Temp.Internal.Core.Event


-- | This module provides types and functions for combining partial configs
--   into a complete configs to ultimately make a <a>Plan</a>.
--   
--   This module has two classes of types.
--   
--   Types like <a>ProcessConfig</a> that could be used by any library that
--   needs to combine process options.
--   
--   Finally it has types and functions for creating <a>Plan</a>s that use
--   temporary resources. This is used to create the default behavior of
--   <a>startConfig</a> and related functions. |
module Database.Postgres.Temp.Internal.Config

-- | <a>Accum</a> is a monoid.
--   
--   It's <a>&lt;&gt;</a> behavior is analogous to 1 and 0 with <a>*</a>.
--   Think of <a>DontCare</a> as 1 and <a>Zlich</a> as 0.
--   
--   The behavior of <a>Merge</a> is like <a>Just</a>s.
data Accum a
DontCare :: Accum a
Zlich :: Accum a
Merge :: a -> Accum a

-- | The environment variables can be declared to inherit from the running
--   process or they can be specifically added.
data EnvironmentVariables
EnvironmentVariables :: Last Bool -> Map String String -> EnvironmentVariables
[inherit] :: EnvironmentVariables -> Last Bool
[specific] :: EnvironmentVariables -> Map String String

-- | Combine the current environment (if indicated by <a>inherit</a>) with
--   <a>specific</a>.
completeEnvironmentVariables :: [(String, String)] -> EnvironmentVariables -> Either [String] [(String, String)]

-- | A type to help combine command line Args.
data CommandLineArgs
CommandLineArgs :: Map String (Maybe String) -> Map Int String -> CommandLineArgs

-- | Args of the form <tt>-h foo</tt>, <tt>--host=foo</tt> and
--   <tt>--switch</tt>. The key is <a>mappend</a>ed with value so the key
--   should include the space or equals (as shown in the first two examples
--   respectively). The <a>Dual</a> monoid is used so the last key wins.
[keyBased] :: CommandLineArgs -> Map String (Maybe String)

-- | Args that appear at the end of the key based Args. The <a>Dual</a>
--   monoid is used so the last key wins.
[indexBased] :: CommandLineArgs -> Map Int String

-- | This convert the <a>CommandLineArgs</a> to '[String]'.
completeCommandLineArgs :: CommandLineArgs -> [String]

-- | Process configuration
data ProcessConfig
ProcessConfig :: EnvironmentVariables -> CommandLineArgs -> Last Handle -> Last Handle -> Last Handle -> ProcessConfig

-- | A monoid for combine environment variables or replacing them. for the
--   maps the <a>Dual</a> monoid is used. So the last key wins.
[environmentVariables] :: ProcessConfig -> EnvironmentVariables

-- | A monoid for combine command line Args or replacing them.
[commandLine] :: ProcessConfig -> CommandLineArgs

-- | A monoid for configuring the standard input <a>Handle</a>.
[stdIn] :: ProcessConfig -> Last Handle

-- | A monoid for configuring the standard output <a>Handle</a>.
[stdOut] :: ProcessConfig -> Last Handle

-- | A monoid for configuring the standard error <a>Handle</a>.
[stdErr] :: ProcessConfig -> Last Handle

-- | The <a>standardProcessConfig</a> sets the handles to <a>stdin</a>,
--   <a>stdout</a> and <a>stderr</a> and inherits the environment variables
--   from the calling process.
standardProcessConfig :: ProcessConfig

-- | A global reference to <tt>/dev/null</tt> <a>Handle</a>.
devNull :: Handle

-- | <a>silentProcessConfig</a> sets the handles to <tt>/dev/null</tt> and
--   inherits the environment variables from the calling process.
silentProcessConfig :: ProcessConfig

-- | Turn a <a>ProcessConfig</a> into a <a>ProcessConfig</a>. Fails if any
--   values are missing.
completeProcessConfig :: [(String, String)] -> ProcessConfig -> Either [String] CompleteProcessConfig

-- | A type to track whether a file is temporary and needs to be cleaned
--   up.
data CompleteDirectoryType
CPermanent :: FilePath -> CompleteDirectoryType
CTemporary :: FilePath -> CompleteDirectoryType

-- | Get the file path of a <a>CompleteDirectoryType</a>, regardless if it
--   is a <a>CPermanent</a> or <a>CTemporary</a> type.
toFilePath :: CompleteDirectoryType -> FilePath

-- | Used to specify a <a>Temporary</a> folder that is automatically
--   cleaned up or a <a>Permanent</a> folder which is not automatically
--   cleaned up.
data DirectoryType

-- | A permanent file that should not be generated.
Permanent :: FilePath -> DirectoryType

-- | A temporary file that needs to generated.
Temporary :: DirectoryType

-- | Either create a<a>CTemporary</a> directory or do create the directory
--   if it does not exist to a <a>CPermanent</a> one.
setupDirectoryType :: String -> String -> DirectoryType -> IO CompleteDirectoryType

-- | Either remove a <a>CTemporary</a> directory or do nothing to a
--   <a>CPermanent</a> one.
cleanupDirectoryType :: CompleteDirectoryType -> IO ()

-- | Turn a <a>Config</a> into a <a>CompletePostgresPlan</a>. Fails if any
--   values are missing.
completePostgresPlan :: [(String, String)] -> Config -> Either [String] CompletePostgresPlan

-- | Turn a <a>Config</a> into a <a>Plan</a>. Fails if any values are
--   missing.
completePlan :: [(String, String)] -> String -> Config -> Either [String] Plan

-- | The high level options for overriding default behavior.
data Config
Config :: Last Logger -> Accum ProcessConfig -> Last (Maybe CopyDirectoryCommand) -> Accum ProcessConfig -> ProcessConfig -> Options -> [(String, String)] -> Last Int -> DirectoryType -> DirectoryType -> Last (Maybe Int) -> Last FilePath -> Last (Maybe (Bool, FilePath)) -> Config

-- | Internal <a>Event</a> logger.
[logger] :: Config -> Last Logger

-- | Monoid for accumulating <tt>initdb</tt> configuration.
[initDbConfig] :: Config -> Accum ProcessConfig

-- | An optional data directory copy command.
[copyConfig] :: Config -> Last (Maybe CopyDirectoryCommand)

-- | Monoid for accumulating <tt>createdb</tt> configuration.
[createDbConfig] :: Config -> Accum ProcessConfig

-- | The <tt>postgres</tt> process configuration.
[postgresConfig] :: Config -> ProcessConfig

-- | The additional client connection options.
[connectionOptions] :: Config -> Options

-- | The <tt>postgresql.conf</tt> configuration file.
[postgresConfigFile] :: Config -> [(String, String)]

-- | The amount of microseconds to attempt to connect to <tt>postgres</tt>
--   before throwing <a>ConnectionTimedOut</a>
[connectionTimeout] :: Config -> Last Int

-- | Override the default temporary UNIX socket directory by setting this.
[socketDirectory] :: Config -> DirectoryType

-- | Override the default temporary data directory by passing in
--   <a>Permanent</a> <tt>DIRECTORY</tt>.
[dataDirectory] :: Config -> DirectoryType

-- | A monoid for using an existing port (via <a>Just</a>
--   <tt>PORT_NUMBER</tt>) or requesting a free port (via a
--   <a>Nothing</a>).
[port] :: Config -> Last (Maybe Int)

-- | The directory used to create other temporary directories. Defaults to
--   <tt>/tmp</tt>.
[temporaryDirectory] :: Config -> Last FilePath
[initDbCache] :: Config -> Last (Maybe (Bool, FilePath))

-- | Copy command used to create a data directory. If <tt>initdb</tt> used
--   to create the data directory directly this is not needed.
--   
--   If <a>destinationDirectory</a> is Nothing then the
--   <a>dataDirectory</a> (which might be generated) is used.
data CopyDirectoryCommand
CopyDirectoryCommand :: FilePath -> Maybe FilePath -> Bool -> CopyDirectoryCommand
[sourceDirectory] :: CopyDirectoryCommand -> FilePath
[destinationDirectory] :: CopyDirectoryCommand -> Maybe FilePath
[useCopyOnWrite] :: CopyDirectoryCommand -> Bool

-- | Create a <a>Config</a> that sets the command line options of all
--   processes (<tt>initdb</tt>, <tt>postgres</tt> and <tt>createdb</tt>).
--   This the <tt>generated</tt> plan that is combined with the
--   <tt>extra</tt> plan from <a>startConfig</a>.
toPlan :: Bool -> Bool -> Int -> FilePath -> FilePath -> Config

-- | Create all the temporary resources from a <a>Config</a>. This also
--   combines the <a>Config</a> from <a>toPlan</a> with the <tt>extra</tt>
--   <a>Config</a> passed in.
setupConfig :: Config -> IO Resources

-- | Free the temporary resources created by <a>setupConfig</a>.
cleanupConfig :: Resources -> IO ()

-- | Display a <a>Config</a>.
prettyPrintConfig :: Config -> String

-- | <a>Resources</a> holds a description of the temporary folders (if
--   there are any) and includes the final <a>Plan</a> that can be used
--   with <a>startPlan</a>. See <a>setupConfig</a> for an example of how to
--   create a <a>Resources</a>.
data Resources
Resources :: Plan -> CompleteDirectoryType -> CompleteDirectoryType -> FilePath -> Maybe (Bool, FilePath) -> Resources

-- | Final <a>Plan</a>. See <a>startPlan</a> for information on
--   <a>Plan</a>s.
[resourcesPlan] :: Resources -> Plan

-- | The used to potentially cleanup the temporary unix socket directory.
[resourcesSocketDirectory] :: Resources -> CompleteDirectoryType

-- | The data directory. Used to track if a temporary directory was used.
[resourcesDataDir] :: Resources -> CompleteDirectoryType

-- | The directory where other temporary directories are created. Usually
--   @/tmp.
[resourcesTemporaryDir] :: Resources -> FilePath
[resourcesInitDbCache] :: Resources -> Maybe (Bool, FilePath)

-- | Make the <a>resourcesDataDir</a> <a>CPermanent</a> so it will not get
--   cleaned up.
makeResourcesDataDirPermanent :: Resources -> Resources

-- | Attempt to create a config from a <a>Options</a>. This is useful if
--   want to create a database owned by a specific user you will also log
--   in as among other use cases. It is possible some <a>Options</a> are
--   not supported so don't hesitate to open an issue on github if you find
--   one.
optionsToConfig :: Options -> Config
instance GHC.Base.Monoid Database.Postgres.Temp.Internal.Config.Config
instance GHC.Base.Semigroup Database.Postgres.Temp.Internal.Config.Config
instance GHC.Generics.Generic Database.Postgres.Temp.Internal.Config.Config
instance GHC.Classes.Ord Database.Postgres.Temp.Internal.Config.CopyDirectoryCommand
instance GHC.Classes.Eq Database.Postgres.Temp.Internal.Config.CopyDirectoryCommand
instance GHC.Show.Show Database.Postgres.Temp.Internal.Config.CopyDirectoryCommand
instance GHC.Classes.Ord Database.Postgres.Temp.Internal.Config.DirectoryType
instance GHC.Classes.Eq Database.Postgres.Temp.Internal.Config.DirectoryType
instance GHC.Show.Show Database.Postgres.Temp.Internal.Config.DirectoryType
instance Control.DeepSeq.NFData Database.Postgres.Temp.Internal.Config.CompleteDirectoryType
instance GHC.Generics.Generic Database.Postgres.Temp.Internal.Config.CompleteDirectoryType
instance GHC.Classes.Ord Database.Postgres.Temp.Internal.Config.CompleteDirectoryType
instance GHC.Classes.Eq Database.Postgres.Temp.Internal.Config.CompleteDirectoryType
instance GHC.Show.Show Database.Postgres.Temp.Internal.Config.CompleteDirectoryType
instance GHC.Base.Monoid Database.Postgres.Temp.Internal.Config.ProcessConfig
instance GHC.Base.Semigroup Database.Postgres.Temp.Internal.Config.ProcessConfig
instance GHC.Show.Show Database.Postgres.Temp.Internal.Config.ProcessConfig
instance GHC.Classes.Eq Database.Postgres.Temp.Internal.Config.ProcessConfig
instance GHC.Generics.Generic Database.Postgres.Temp.Internal.Config.ProcessConfig
instance GHC.Base.Monoid Database.Postgres.Temp.Internal.Config.CommandLineArgs
instance GHC.Classes.Eq Database.Postgres.Temp.Internal.Config.CommandLineArgs
instance GHC.Show.Show Database.Postgres.Temp.Internal.Config.CommandLineArgs
instance GHC.Generics.Generic Database.Postgres.Temp.Internal.Config.CommandLineArgs
instance GHC.Classes.Eq Database.Postgres.Temp.Internal.Config.EnvironmentVariables
instance GHC.Show.Show Database.Postgres.Temp.Internal.Config.EnvironmentVariables
instance GHC.Generics.Generic Database.Postgres.Temp.Internal.Config.EnvironmentVariables
instance GHC.Base.Functor Database.Postgres.Temp.Internal.Config.Accum
instance GHC.Classes.Ord a => GHC.Classes.Ord (Database.Postgres.Temp.Internal.Config.Accum a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Database.Postgres.Temp.Internal.Config.Accum a)
instance GHC.Show.Show a => GHC.Show.Show (Database.Postgres.Temp.Internal.Config.Accum a)
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Config.Resources
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Config.Config
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Config.CopyDirectoryCommand
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Config.DirectoryType
instance GHC.Base.Semigroup Database.Postgres.Temp.Internal.Config.DirectoryType
instance GHC.Base.Monoid Database.Postgres.Temp.Internal.Config.DirectoryType
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Config.CompleteDirectoryType
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Config.ProcessConfig
instance GHC.Base.Semigroup Database.Postgres.Temp.Internal.Config.CommandLineArgs
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Config.CommandLineArgs
instance GHC.Base.Semigroup Database.Postgres.Temp.Internal.Config.EnvironmentVariables
instance GHC.Base.Monoid Database.Postgres.Temp.Internal.Config.EnvironmentVariables
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Config.EnvironmentVariables
instance GHC.Base.Applicative Database.Postgres.Temp.Internal.Config.Accum
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Database.Postgres.Temp.Internal.Config.Accum a)
instance GHC.Base.Monoid a => GHC.Base.Monoid (Database.Postgres.Temp.Internal.Config.Accum a)


-- | This module provides the high level functions that are re-exported by
--   <tt>Database.Postgres.Temp</tt>. Additionally it includes some
--   identifiers that are used for testing but are not exported.
module Database.Postgres.Temp.Internal

-- | Handle for holding temporary resources, the <tt>postgres</tt> process
--   handle and <tt>postgres</tt> connection information. The <a>DB</a>
--   also includes the final plan used to start <tt>initdb</tt>,
--   <tt>createdb</tt> and <tt>postgres</tt>.
data DB
DB :: Resources -> PostgresProcess -> DB

-- | Temporary resources and the final <a>Plan</a>.
[dbResources] :: DB -> Resources

-- | <tt>postgres</tt> process handle and the connection options.
[dbPostgresProcess] :: DB -> PostgresProcess

-- | Convert a <a>DB</a> to a connection string. Alternatively one can
--   access the <a>Options</a> using <a>toConnectionOptions</a>.
toConnectionString :: DB -> ByteString

-- | Convert a <a>DB</a> to a connection <a>Options</a> type.
toConnectionOptions :: DB -> Options

-- | Access the data directory. This was either generated or specified
--   explicitly when creating the <a>Config</a>
toDataDirectory :: DB -> FilePath

-- | Make the data directory permanent. Useful for debugging. If you are
--   using <a>with</a> or <a>withConfig</a> this function will not modify
--   the <a>DB</a> that is passed for cleanup. You will need to setup your
--   own bracket like
--   
--   <pre>
--   bracket (fmap <a>makeDataDirectoryPermanent</a> <a>start</a>) (either mempty <a>stop</a>)
--   </pre>
makeDataDirectoryPermanent :: DB -> DB

-- | Get the directory that is used to create other temporary directories
toTemporaryDirectory :: DB -> FilePath

-- | Get the final <tt>postgresql.conf</tt>
toPostgresqlConfigFile :: DB -> String

-- | The fastest config we can make.
--   
--   <pre>
--   shared_buffers = 12MB
--   fsync = off
--   synchronous_commit = off
--   full_page_writes = off
--   log_min_messages = PANIC
--   log_min_error_statement = PANIC
--   log_statement = none
--   client_min_messages = ERROR
--   </pre>
fastPostgresConfig :: [(String, String)]

-- | The default configuration. This will create a database called
--   "postgres" via <tt>initdb</tt> (it's default behavior). It will create
--   a temporary directory for the data and a temporary directory for a
--   unix socket and listen on 127.0.0.1 and ::1 on a random port.
--   Additionally it will use the following "postgresql.conf" which is
--   optimized for performance.
--   
--   <pre>
--   shared_buffers = 12MB
--   fsync = off
--   synchronous_commit = off
--   full_page_writes = off
--   log_min_messages = PANIC
--   log_min_error_statement = PANIC
--   log_statement = none
--   client_min_messages = ERROR
--   commit_delay = 100000
--   wal_level = minimal
--   archive_mode = off
--   max_wal_senders = 0
--   </pre>
--   
--   <a>defaultConfig</a> also passes the <tt>--no-sync</tt> flag to
--   <tt>initdb</tt>.
--   
--   If you would like to customize this behavior you can start with the
--   <a>defaultConfig</a> and overwrite fields or combine a
--   <a>defaultConfig</a> with another <a>Config</a> using <a>&lt;&gt;</a>
--   (<a>mappend</a>).
--   
--   Alternatively you can eschew <a>defaultConfig</a> altogether, however
--   your <tt>postgres</tt> might start and run faster if you use
--   <a>defaultConfig</a>.
--   
--   The <a>defaultConfig</a> redirects all output to <tt>/dev/null</tt>.
--   See <a>verboseConfig</a> for a version that logs more output.
--   
--   To append additional lines to "postgresql.conf" file create a custom
--   <a>Config</a> like the following.
--   
--   <pre>
--   custom = defaultConfig &lt;&gt; mempty
--     { <a>postgresConfigFile</a> =
--         [ ("wal_level, "replica")
--         , ("archive_mode", on")
--         , ("max_wal_senders", "2")
--         , ("fsync", "on")
--         , ("synchronous_commit", "on")
--         ]
--     }
--   </pre>
--   
--   As an alternative to using <a>defaultConfig</a> one could create a
--   config from connections parameters using
--   <a>optionsToDefaultConfig</a>.
defaultConfig :: Config

-- | Default configuration for PostgreSQL versions 9.3 and greater but less
--   than 10.
--   
--   If you get an error that "--no-sync" is an invalid parameter then you
--   should use this config.
defaultConfig_9_3_10 :: Config

-- | Default postgres options
verbosePostgresConfig :: [(String, String)]

-- | This is similar to <a>defaultConfig</a> but it logs as much as
--   possible..
verboseConfig :: Config

-- | Create zero or more temporary resources and use them to make a
--   <a>Config</a>.
--   
--   The passed in config is inspected and a generated config is created.
--   The final config is built by
--   
--   <pre>
--   generated <a>&lt;&gt;</a> extra
--   </pre>
--   
--   Based on the value of <a>socketDirectory</a> a "postgresql.conf" is
--   created with:
--   
--   <pre>
--   listen_addresses = '127.0.0.1, ::1'
--   unix_socket_directories = 'SOCKET_DIRECTORY'
--   </pre>
--   
--   Additionally the <tt>generated</tt> <a>Config</a> also:
--   
--   <ul>
--   <li>Sets a <a>connectionTimeout</a> of one minute.</li>
--   <li>Redirects output to <tt>/dev/null</tt>.</li>
--   </ul>
--   
--   All of these values can be overrided by the <tt>extra</tt> config.
--   
--   The returned <a>DB</a> requires cleanup. <a>startConfig</a> should be
--   used with a <a>bracket</a> and <a>stop</a>, e.g.
--   
--   <pre>
--   <a>withConfig</a> :: <a>Config</a> -&gt; (<a>DB</a> -&gt; IO a) -&gt; IO (Either <a>StartError</a> a)
--   <a>withConfig</a> plan f = <a>bracket</a> (<a>startConfig</a> plan) (either mempty <a>stop</a>) $
--     either (pure . Left) (fmap Right . f)
--   </pre>
--   
--   or just use <a>withConfig</a>. If you are calling <a>startConfig</a>
--   you probably want <a>withConfig</a> anyway.
startConfig :: Config -> IO (Either StartError DB)

-- | Default start behavior. Equivalent to calling <a>startConfig</a> with
--   the <a>defaultConfig</a>.
start :: IO (Either StartError DB)

-- | Stop the <tt>postgres</tt> process and cleanup any temporary resources
--   that might have been created.
stop :: DB -> IO ()

-- | Only stop the <tt>postgres</tt> process but leave any temporary
--   resources. Useful for testing backup strategies when used in
--   conjunction with <a>restart</a> or <a>withRestart</a>.
stopPostgres :: DB -> IO ExitCode

-- | Only stop the <tt>postgres</tt> process but leave any temporary
--   resources. In contrast to <a>stopPostgres</a> this function makes sure
--   <tt>postgres</tt> has time to properly write files to the data
--   directory.
stopPostgresGracefully :: DB -> IO ExitCode

-- | Restart the <tt>postgres</tt> from <a>DB</a> using the prior
--   <a>Config</a>. This will also start an instance previously stoppped
--   with <a>stopPostgres</a>.
restart :: DB -> IO (Either StartError DB)

-- | Exception safe database create with options. See <a>startConfig</a>
--   for more details. Calls <a>stop</a> even in the face of exceptions.
withConfig :: Config -> (DB -> IO a) -> IO (Either StartError a)

-- | Default expectation safe interface. Equivalent to
--   
--   <pre>
--   <a>with</a> = <a>withConfig</a> <a>defaultConfig</a>
--   </pre>
with :: (DB -> IO a) -> IO (Either StartError a)

-- | Exception safe version of <a>restart</a>.
withRestart :: DB -> (DB -> IO a) -> IO (Either StartError a)

-- | Attempt to create a <a>Config</a> from a <a>Options</a>. Useful if you
--   want to create a database owned by a specific user you will also login
--   with among other use cases.
optionsToDefaultConfig :: Options -> Config

-- | Display a <a>DB</a>.
prettyPrintDB :: DB -> String

-- | Configuration for the <tt>initdb</tt> data directory cache.
data CacheConfig
CacheConfig :: FilePath -> DirectoryType -> Bool -> CacheConfig

-- | Root temporary directory used if <a>cacheDirectoryType</a> is set to
--   <a>Temporary</a>. <tt>/tmp</tt> is a good default.
[cacheTemporaryDirectory] :: CacheConfig -> FilePath

-- | Used to specify is a <a>Permanent</a> or <a>Temporary</a> directory
--   should be used. <a>defaultCacheConfig</a> uses <a>Permanent</a>
--   <tt>~/.tmp-postgres</tt> by default.
[cacheDirectoryType] :: CacheConfig -> DirectoryType

-- | Some operatoring system versions support flags for <tt>cp</tt> that
--   allow "copy on write" which is about 2x faster.
--   <a>defaultCacheConfig</a> attempts to determine if the <tt>cp</tt> on
--   the path supports copy on write and sets this to <a>True</a> if it
--   does.
[cacheUseCopyOnWrite] :: CacheConfig -> Bool

-- | A handle to cache temporary resources and configuration.
data Cache
Cache :: Bool -> CompleteDirectoryType -> Cache
[cacheResourcesCow] :: Cache -> Bool
[cacheResourcesDirectory] :: Cache -> CompleteDirectoryType

-- | A bool that is <a>True</a> if the <tt>cp</tt> on the path supports
--   "copy on write" flags.
cowCheck :: Bool

-- | <a>defaultCacheConfig</a> attempts to determine if the <tt>cp</tt> on
--   the path supports "copy on write" flags and if it does, sets
--   <a>cacheUseCopyOnWrite</a> to <a>True</a>.
--   
--   It sets <a>cacheDirectoryType</a> to <a>Permanent</a>
--   <tt>~/.tmp-postgres</tt> and <a>cacheTemporaryDirectory</a> to
--   <tt>/tmp</tt> (but this is not used when <a>Permanent</a> is set).
defaultCacheConfig :: CacheConfig

-- | Setup the <tt>initdb</tt> cache folder.
setupInitDbCache :: CacheConfig -> IO Cache

-- | Cleanup the cache directory if it was <a>Temporary</a>.
cleanupInitDbCache :: Cache -> IO ()

-- | Enable <tt>initdb</tt> data directory caching. This can lead to a 4x
--   speedup.
--   
--   Exception safe version of <a>setupInitDbCache</a>. Equivalent to
--   
--   <pre>
--   <a>withDbCacheConfig</a> = bracket (<a>setupInitDbCache</a> config) <a>cleanupInitDbCache</a>
--   </pre>
withDbCacheConfig :: CacheConfig -> (Cache -> IO a) -> IO a

-- | Equivalent to <a>withDbCacheConfig</a> with the <a>CacheConfig</a>
--   <a>defaultCacheConfig</a> makes.
--   
--   Here is an example using caching:
--   
--   <pre>
--   withDbCache $ \cache -&gt; do
--     withCache (cacheConfig cache) $ \db -&gt; ...
--     withCache (cacheConfig cache) $ \db -&gt; ...
--   </pre>
withDbCache :: (Cache -> IO a) -> IO a

-- | Helper to make a <a>Config</a> out of caching info.
cacheConfig :: Cache -> Config

-- | A type to track a possibly temporary snapshot directory
newtype Snapshot
Snapshot :: CompleteDirectoryType -> Snapshot
[unSnapshot] :: Snapshot -> CompleteDirectoryType

-- | Shutdown the database and copy the directory to a folder.
takeSnapshot :: DB -> IO (Either StartError Snapshot)

-- | Cleanup any temporary resources used for the snapshot.
cleanupSnapshot :: Snapshot -> IO ()

-- | Exception safe method for taking a file system level copy of the
--   database cluster.
--   
--   Snapshots are useful if you would like to start every test from a
--   migrated database and the migration process is more time consuming
--   then copying the additional data.
--   
--   Here is an example with caching and snapshots:
--   
--   <pre>
--   withDbCache $ \cache -&gt; withConfig (cacheConfig cache) $ \db -&gt;
--     migrate db
--     withSnapshot Temporary db $ \snapshot -&gt; do
--       withConfig (snapshotConfig db) $ \migratedDb -&gt; ...
--       withConfig (snapshotConfig db) $ \migratedDb -&gt; ...
--       withConfig (snapshotConfig db) $ \migratedDb -&gt; ...
--   </pre>
--   
--   The <a>Snapshot</a>s are ephemeral. If you would like the
--   <a>Snapshot</a>s to persistent consider using <a>cacheAction</a>
--   instead.
withSnapshot :: DB -> (Snapshot -> IO a) -> IO (Either StartError a)

-- | Convert a snapshot into a <a>Config</a> that includes a
--   <a>copyConfig</a> for copying the snapshot directory to a temporary
--   directory.
snapshotConfig :: Snapshot -> Config

-- | Check to see if a cached data directory exists.
--   
--   If the file path does not exist the <tt>initial</tt> config is used to
--   start a <tt>postgres</tt> instance. After which the <tt>action</tt> is
--   applied, the data directory is cached and <tt>postgres</tt> is
--   shutdown.
--   
--   <a>cacheAction</a> <a>mappend</a>s a config to copy the cached data
--   directory on startup onto the <tt>initial</tt> config and returns it.
--   In other words:
--   
--   <pre>
--   initialConfig &lt;&gt; configFromCachePath
--   </pre>
--   
--   <a>cacheAction</a> can be used to create a snapshot of migrated
--   database and not remigrate as long as the migration does not change.
--   See <a>withSnapshot</a> for a ephemeral version of taking snapshots.
cacheAction :: FilePath -> (DB -> IO ()) -> Config -> IO (Either StartError Config)
instance Control.DeepSeq.NFData Database.Postgres.Temp.Internal.Snapshot
instance GHC.Generics.Generic Database.Postgres.Temp.Internal.Snapshot
instance Control.DeepSeq.NFData Database.Postgres.Temp.Internal.Cache
instance GHC.Generics.Generic Database.Postgres.Temp.Internal.Cache
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.DB


-- | This module provides functions for creating a temporary
--   <tt>postgres</tt> instance. By default it will create a temporary data
--   directory and a temporary directory for a UNIX domain socket for
--   <tt>postgres</tt> to listen on in addition to listening on
--   <tt>127.0.0.1</tt> and <tt>::1</tt>.
--   
--   Here is an example using the expection safe <a>with</a> function:
--   
--   <pre>
--   <a>with</a> $ \db -&gt; <a>bracket</a>
--      (<a>connectPostgreSQL</a> (<a>toConnectionString</a> db))
--      <a>close</a> $
--      \conn -&gt; <a>execute_</a> conn "CREATE TABLE foo (id int)"
--   </pre>
--   
--   To extend or override the defaults use <a>withConfig</a> (or
--   <a>startConfig</a>).
--   
--   <tt>tmp-postgres</tt> ultimately calls <tt>initdb</tt> (optionally),
--   <tt>postgres</tt> and <tt>createdb</tt> (optionally).
--   
--   All of the command line, environment variables and configuration files
--   that are generated by default for the respective executables can be
--   extended or overriden.
--   
--   In general <tt>tmp-postgres</tt> is useful if you want a clean
--   temporary <tt>postgres</tt> and do not want to worry about clashing
--   with an existing postgres instance (or needing to ensure
--   <tt>postgres</tt> is already running).
--   
--   Here are some different use cases for <tt>tmp-postgres</tt> and their
--   respective configurations:
--   
--   <ul>
--   <li>The default <a>with</a> and <a>start</a> functions can be used to
--   make a sandboxed temporary database for testing.</li>
--   <li>By disabling <tt>initdb</tt> one could run a temporary isolated
--   postgres on a base backup to test a migration.</li>
--   <li>By using the <a>stopPostgres</a> and <a>withRestart</a> functions
--   one can test backup strategies.</li>
--   </ul>
--   
--   WARNING! Ubuntu's PostgreSQL installation does not put <tt>initdb</tt>
--   on the <tt>PATH</tt>. We need to add it manually. The necessary
--   binaries are in the <tt>/usr/lib/postgresql/VERSION/bin/</tt>
--   directory, and should be added to the <tt>PATH</tt>
--   
--   <pre>
--   echo "export PATH=$PATH:/usr/lib/postgresql/VERSION/bin/" &gt;&gt; /home/ubuntu/.bashrc
--   </pre>
module Database.Postgres.Temp

-- | Default expectation safe interface. Equivalent to
--   
--   <pre>
--   <a>with</a> = <a>withConfig</a> <a>defaultConfig</a>
--   </pre>
with :: (DB -> IO a) -> IO (Either StartError a)

-- | Exception safe database create with options. See <a>startConfig</a>
--   for more details. Calls <a>stop</a> even in the face of exceptions.
withConfig :: Config -> (DB -> IO a) -> IO (Either StartError a)

-- | Exception safe version of <a>restart</a>.
withRestart :: DB -> (DB -> IO a) -> IO (Either StartError a)

-- | The default configuration. This will create a database called
--   "postgres" via <tt>initdb</tt> (it's default behavior). It will create
--   a temporary directory for the data and a temporary directory for a
--   unix socket and listen on 127.0.0.1 and ::1 on a random port.
--   Additionally it will use the following "postgresql.conf" which is
--   optimized for performance.
--   
--   <pre>
--   shared_buffers = 12MB
--   fsync = off
--   synchronous_commit = off
--   full_page_writes = off
--   log_min_messages = PANIC
--   log_min_error_statement = PANIC
--   log_statement = none
--   client_min_messages = ERROR
--   commit_delay = 100000
--   wal_level = minimal
--   archive_mode = off
--   max_wal_senders = 0
--   </pre>
--   
--   <a>defaultConfig</a> also passes the <tt>--no-sync</tt> flag to
--   <tt>initdb</tt>.
--   
--   If you would like to customize this behavior you can start with the
--   <a>defaultConfig</a> and overwrite fields or combine a
--   <a>defaultConfig</a> with another <a>Config</a> using <a>&lt;&gt;</a>
--   (<a>mappend</a>).
--   
--   Alternatively you can eschew <a>defaultConfig</a> altogether, however
--   your <tt>postgres</tt> might start and run faster if you use
--   <a>defaultConfig</a>.
--   
--   The <a>defaultConfig</a> redirects all output to <tt>/dev/null</tt>.
--   See <a>verboseConfig</a> for a version that logs more output.
--   
--   To append additional lines to "postgresql.conf" file create a custom
--   <a>Config</a> like the following.
--   
--   <pre>
--   custom = defaultConfig &lt;&gt; mempty
--     { <a>postgresConfigFile</a> =
--         [ ("wal_level, "replica")
--         , ("archive_mode", on")
--         , ("max_wal_senders", "2")
--         , ("fsync", "on")
--         , ("synchronous_commit", "on")
--         ]
--     }
--   </pre>
--   
--   As an alternative to using <a>defaultConfig</a> one could create a
--   config from connections parameters using
--   <a>optionsToDefaultConfig</a>.
defaultConfig :: Config

-- | Default configuration for PostgreSQL versions 9.3 and greater but less
--   than 10.
--   
--   If you get an error that "--no-sync" is an invalid parameter then you
--   should use this config.
defaultConfig_9_3_10 :: Config

-- | This is similar to <a>defaultConfig</a> but it logs as much as
--   possible..
verboseConfig :: Config

-- | Attempt to create a <a>Config</a> from a <a>Options</a>. Useful if you
--   want to create a database owned by a specific user you will also login
--   with among other use cases.
optionsToDefaultConfig :: Options -> Config

-- | Handle for holding temporary resources, the <tt>postgres</tt> process
--   handle and <tt>postgres</tt> connection information. The <a>DB</a>
--   also includes the final plan used to start <tt>initdb</tt>,
--   <tt>createdb</tt> and <tt>postgres</tt>.
data DB

-- | Convert a <a>DB</a> to a connection string. Alternatively one can
--   access the <a>Options</a> using <a>toConnectionOptions</a>.
toConnectionString :: DB -> ByteString

-- | Convert a <a>DB</a> to a connection <a>Options</a> type.
toConnectionOptions :: DB -> Options

-- | Access the data directory. This was either generated or specified
--   explicitly when creating the <a>Config</a>
toDataDirectory :: DB -> FilePath

-- | Get the directory that is used to create other temporary directories
toTemporaryDirectory :: DB -> FilePath

-- | Get the final <tt>postgresql.conf</tt>
toPostgresqlConfigFile :: DB -> String

-- | Make the data directory permanent. Useful for debugging. If you are
--   using <a>with</a> or <a>withConfig</a> this function will not modify
--   the <a>DB</a> that is passed for cleanup. You will need to setup your
--   own bracket like
--   
--   <pre>
--   bracket (fmap <a>makeDataDirectoryPermanent</a> <a>start</a>) (either mempty <a>stop</a>)
--   </pre>
makeDataDirectoryPermanent :: DB -> DB

-- | Display a <a>DB</a>.
prettyPrintDB :: DB -> String

-- | Default start behavior. Equivalent to calling <a>startConfig</a> with
--   the <a>defaultConfig</a>.
start :: IO (Either StartError DB)

-- | Create zero or more temporary resources and use them to make a
--   <a>Config</a>.
--   
--   The passed in config is inspected and a generated config is created.
--   The final config is built by
--   
--   <pre>
--   generated <a>&lt;&gt;</a> extra
--   </pre>
--   
--   Based on the value of <a>socketDirectory</a> a "postgresql.conf" is
--   created with:
--   
--   <pre>
--   listen_addresses = '127.0.0.1, ::1'
--   unix_socket_directories = 'SOCKET_DIRECTORY'
--   </pre>
--   
--   Additionally the <tt>generated</tt> <a>Config</a> also:
--   
--   <ul>
--   <li>Sets a <a>connectionTimeout</a> of one minute.</li>
--   <li>Redirects output to <tt>/dev/null</tt>.</li>
--   </ul>
--   
--   All of these values can be overrided by the <tt>extra</tt> config.
--   
--   The returned <a>DB</a> requires cleanup. <a>startConfig</a> should be
--   used with a <a>bracket</a> and <a>stop</a>, e.g.
--   
--   <pre>
--   <a>withConfig</a> :: <a>Config</a> -&gt; (<a>DB</a> -&gt; IO a) -&gt; IO (Either <a>StartError</a> a)
--   <a>withConfig</a> plan f = <a>bracket</a> (<a>startConfig</a> plan) (either mempty <a>stop</a>) $
--     either (pure . Left) (fmap Right . f)
--   </pre>
--   
--   or just use <a>withConfig</a>. If you are calling <a>startConfig</a>
--   you probably want <a>withConfig</a> anyway.
startConfig :: Config -> IO (Either StartError DB)

-- | Stop the <tt>postgres</tt> process and cleanup any temporary resources
--   that might have been created.
stop :: DB -> IO ()

-- | Restart the <tt>postgres</tt> from <a>DB</a> using the prior
--   <a>Config</a>. This will also start an instance previously stoppped
--   with <a>stopPostgres</a>.
restart :: DB -> IO (Either StartError DB)

-- | Only stop the <tt>postgres</tt> process but leave any temporary
--   resources. Useful for testing backup strategies when used in
--   conjunction with <a>restart</a> or <a>withRestart</a>.
stopPostgres :: DB -> IO ExitCode

-- | Equivalent to <a>withDbCacheConfig</a> with the <a>CacheConfig</a>
--   <a>defaultCacheConfig</a> makes.
--   
--   Here is an example using caching:
--   
--   <pre>
--   withDbCache $ \cache -&gt; do
--     withCache (cacheConfig cache) $ \db -&gt; ...
--     withCache (cacheConfig cache) $ \db -&gt; ...
--   </pre>
withDbCache :: (Cache -> IO a) -> IO a

-- | Enable <tt>initdb</tt> data directory caching. This can lead to a 4x
--   speedup.
--   
--   Exception safe version of <a>setupInitDbCache</a>. Equivalent to
--   
--   <pre>
--   <a>withDbCacheConfig</a> = bracket (<a>setupInitDbCache</a> config) <a>cleanupInitDbCache</a>
--   </pre>
withDbCacheConfig :: CacheConfig -> (Cache -> IO a) -> IO a

-- | Configuration for the <tt>initdb</tt> data directory cache.
data CacheConfig
CacheConfig :: FilePath -> DirectoryType -> Bool -> CacheConfig

-- | Root temporary directory used if <a>cacheDirectoryType</a> is set to
--   <a>Temporary</a>. <tt>/tmp</tt> is a good default.
[cacheTemporaryDirectory] :: CacheConfig -> FilePath

-- | Used to specify is a <a>Permanent</a> or <a>Temporary</a> directory
--   should be used. <a>defaultCacheConfig</a> uses <a>Permanent</a>
--   <tt>~/.tmp-postgres</tt> by default.
[cacheDirectoryType] :: CacheConfig -> DirectoryType

-- | Some operatoring system versions support flags for <tt>cp</tt> that
--   allow "copy on write" which is about 2x faster.
--   <a>defaultCacheConfig</a> attempts to determine if the <tt>cp</tt> on
--   the path supports copy on write and sets this to <a>True</a> if it
--   does.
[cacheUseCopyOnWrite] :: CacheConfig -> Bool

-- | <a>defaultCacheConfig</a> attempts to determine if the <tt>cp</tt> on
--   the path supports "copy on write" flags and if it does, sets
--   <a>cacheUseCopyOnWrite</a> to <a>True</a>.
--   
--   It sets <a>cacheDirectoryType</a> to <a>Permanent</a>
--   <tt>~/.tmp-postgres</tt> and <a>cacheTemporaryDirectory</a> to
--   <tt>/tmp</tt> (but this is not used when <a>Permanent</a> is set).
defaultCacheConfig :: CacheConfig

-- | A handle to cache temporary resources and configuration.
data Cache

-- | Helper to make a <a>Config</a> out of caching info.
cacheConfig :: Cache -> Config

-- | Setup the <tt>initdb</tt> cache folder.
setupInitDbCache :: CacheConfig -> IO Cache

-- | Cleanup the cache directory if it was <a>Temporary</a>.
cleanupInitDbCache :: Cache -> IO ()

-- | Exception safe method for taking a file system level copy of the
--   database cluster.
--   
--   Snapshots are useful if you would like to start every test from a
--   migrated database and the migration process is more time consuming
--   then copying the additional data.
--   
--   Here is an example with caching and snapshots:
--   
--   <pre>
--   withDbCache $ \cache -&gt; withConfig (cacheConfig cache) $ \db -&gt;
--     migrate db
--     withSnapshot Temporary db $ \snapshot -&gt; do
--       withConfig (snapshotConfig db) $ \migratedDb -&gt; ...
--       withConfig (snapshotConfig db) $ \migratedDb -&gt; ...
--       withConfig (snapshotConfig db) $ \migratedDb -&gt; ...
--   </pre>
--   
--   The <a>Snapshot</a>s are ephemeral. If you would like the
--   <a>Snapshot</a>s to persistent consider using <a>cacheAction</a>
--   instead.
withSnapshot :: DB -> (Snapshot -> IO a) -> IO (Either StartError a)

-- | A type to track a possibly temporary snapshot directory
data Snapshot

-- | Convert a snapshot into a <a>Config</a> that includes a
--   <a>copyConfig</a> for copying the snapshot directory to a temporary
--   directory.
snapshotConfig :: Snapshot -> Config

-- | Shutdown the database and copy the directory to a folder.
takeSnapshot :: DB -> IO (Either StartError Snapshot)

-- | Cleanup any temporary resources used for the snapshot.
cleanupSnapshot :: Snapshot -> IO ()

-- | Check to see if a cached data directory exists.
--   
--   If the file path does not exist the <tt>initial</tt> config is used to
--   start a <tt>postgres</tt> instance. After which the <tt>action</tt> is
--   applied, the data directory is cached and <tt>postgres</tt> is
--   shutdown.
--   
--   <a>cacheAction</a> <a>mappend</a>s a config to copy the cached data
--   directory on startup onto the <tt>initial</tt> config and returns it.
--   In other words:
--   
--   <pre>
--   initialConfig &lt;&gt; configFromCachePath
--   </pre>
--   
--   <a>cacheAction</a> can be used to create a snapshot of migrated
--   database and not remigrate as long as the migration does not change.
--   See <a>withSnapshot</a> for a ephemeral version of taking snapshots.
cacheAction :: FilePath -> (DB -> IO ()) -> Config -> IO (Either StartError Config)

-- | A list of failures that can occur when starting. This is not and
--   exhaustive list but covers the errors that the system catches for the
--   user.
data StartError

-- | <tt>postgres</tt> failed before a connection succeeded. Most likely
--   this is due to invalid configuration
StartPostgresFailed :: ExitCode -> StartError

-- | <tt>initdb</tt> failed. This can be from invalid configuration or
--   using a non-empty data directory
InitDbFailed :: String -> String -> ExitCode -> StartError
[startErrorStdOut] :: StartError -> String
[startErrorStdErr] :: StartError -> String
[startErrorExitCode] :: StartError -> ExitCode

-- | <tt>createdb</tt> failed. This can be from invalid configuration or
--   the database might already exist.
CreateDbFailed :: String -> String -> ExitCode -> StartError
[startErrorStdOut] :: StartError -> String
[startErrorStdErr] :: StartError -> String
[startErrorExitCode] :: StartError -> ExitCode

-- | The <a>Plan</a> was missing info and a complete <a>Plan</a> could not
--   be created.
PlanFailed :: String -> [String] -> StartError

-- | The <a>ProcessConfig</a> was missing info and a
--   <a>CompleteProcessConfig</a> could not be created.
CompleteProcessConfigFailed :: String -> [String] -> StartError

-- | Timed out waiting for <tt>postgres</tt> to accept a connection
ConnectionTimedOut :: StartError
DeleteDbError :: SqlError -> StartError

-- | This will happen if a <a>Plan</a> is missing a <a>initDbConfig</a>.
EmptyDataDirectory :: StartError

-- | This is called if copying a folder cache fails.
CopyCachedInitDbFailed :: String -> ExitCode -> StartError

-- | Failed to find a data directory when trying to get a cached
--   <tt>initdb</tt> folder.
FailedToFindDataDirectory :: String -> StartError

-- | We tried to copy a data directory to a snapshot folder and it failed
SnapshotCopyFailed :: String -> ExitCode -> StartError

-- | The high level options for overriding default behavior.
data Config
Config :: Last Logger -> Accum ProcessConfig -> Last (Maybe CopyDirectoryCommand) -> Accum ProcessConfig -> ProcessConfig -> Options -> [(String, String)] -> Last Int -> DirectoryType -> DirectoryType -> Last (Maybe Int) -> Last FilePath -> Last (Maybe (Bool, FilePath)) -> Config

-- | Internal <a>Event</a> logger.
[logger] :: Config -> Last Logger

-- | Monoid for accumulating <tt>initdb</tt> configuration.
[initDbConfig] :: Config -> Accum ProcessConfig

-- | An optional data directory copy command.
[copyConfig] :: Config -> Last (Maybe CopyDirectoryCommand)

-- | Monoid for accumulating <tt>createdb</tt> configuration.
[createDbConfig] :: Config -> Accum ProcessConfig

-- | The <tt>postgres</tt> process configuration.
[postgresConfig] :: Config -> ProcessConfig

-- | The additional client connection options.
[connectionOptions] :: Config -> Options

-- | The <tt>postgresql.conf</tt> configuration file.
[postgresConfigFile] :: Config -> [(String, String)]

-- | The amount of microseconds to attempt to connect to <tt>postgres</tt>
--   before throwing <a>ConnectionTimedOut</a>
[connectionTimeout] :: Config -> Last Int

-- | Override the default temporary UNIX socket directory by setting this.
[socketDirectory] :: Config -> DirectoryType

-- | Override the default temporary data directory by passing in
--   <a>Permanent</a> <tt>DIRECTORY</tt>.
[dataDirectory] :: Config -> DirectoryType

-- | A monoid for using an existing port (via <a>Just</a>
--   <tt>PORT_NUMBER</tt>) or requesting a free port (via a
--   <a>Nothing</a>).
[port] :: Config -> Last (Maybe Int)

-- | The directory used to create other temporary directories. Defaults to
--   <tt>/tmp</tt>.
[temporaryDirectory] :: Config -> Last FilePath
[initDbCache] :: Config -> Last (Maybe (Bool, FilePath))

-- | Display a <a>Config</a>.
prettyPrintConfig :: Config -> String

-- | Process configuration
data ProcessConfig
ProcessConfig :: EnvironmentVariables -> CommandLineArgs -> Last Handle -> Last Handle -> Last Handle -> ProcessConfig

-- | A monoid for combine environment variables or replacing them. for the
--   maps the <a>Dual</a> monoid is used. So the last key wins.
[environmentVariables] :: ProcessConfig -> EnvironmentVariables

-- | A monoid for combine command line Args or replacing them.
[commandLine] :: ProcessConfig -> CommandLineArgs

-- | A monoid for configuring the standard input <a>Handle</a>.
[stdIn] :: ProcessConfig -> Last Handle

-- | A monoid for configuring the standard output <a>Handle</a>.
[stdOut] :: ProcessConfig -> Last Handle

-- | A monoid for configuring the standard error <a>Handle</a>.
[stdErr] :: ProcessConfig -> Last Handle

-- | The environment variables can be declared to inherit from the running
--   process or they can be specifically added.
data EnvironmentVariables
EnvironmentVariables :: Last Bool -> Map String String -> EnvironmentVariables
[inherit] :: EnvironmentVariables -> Last Bool
[specific] :: EnvironmentVariables -> Map String String

-- | A type to help combine command line Args.
data CommandLineArgs
CommandLineArgs :: Map String (Maybe String) -> Map Int String -> CommandLineArgs

-- | Args of the form <tt>-h foo</tt>, <tt>--host=foo</tt> and
--   <tt>--switch</tt>. The key is <a>mappend</a>ed with value so the key
--   should include the space or equals (as shown in the first two examples
--   respectively). The <a>Dual</a> monoid is used so the last key wins.
[keyBased] :: CommandLineArgs -> Map String (Maybe String)

-- | Args that appear at the end of the key based Args. The <a>Dual</a>
--   monoid is used so the last key wins.
[indexBased] :: CommandLineArgs -> Map Int String

-- | Used to specify a <a>Temporary</a> folder that is automatically
--   cleaned up or a <a>Permanent</a> folder which is not automatically
--   cleaned up.
data DirectoryType

-- | A permanent file that should not be generated.
Permanent :: FilePath -> DirectoryType

-- | A temporary file that needs to generated.
Temporary :: DirectoryType

-- | A type to track whether a file is temporary and needs to be cleaned
--   up.
data CompleteDirectoryType
CPermanent :: FilePath -> CompleteDirectoryType
CTemporary :: FilePath -> CompleteDirectoryType

-- | <a>Accum</a> is a monoid.
--   
--   It's <a>&lt;&gt;</a> behavior is analogous to 1 and 0 with <a>*</a>.
--   Think of <a>DontCare</a> as 1 and <a>Zlich</a> as 0.
--   
--   The behavior of <a>Merge</a> is like <a>Just</a>s.
data Accum a
DontCare :: Accum a
Zlich :: Accum a
Merge :: a -> Accum a

-- | A way to log internal <a>Event</a>s
type Logger = Event -> IO ()

-- | Internal events for debugging
data Event

-- | The first event. This useful for debugging what is actual passed to
--   the <tt>initdb</tt>, <tt>createdb</tt> and <tt>postgres</tt>.
StartPlan :: String -> Event

-- | The second event. Postgres is about to get called
StartPostgres :: Event

-- | The third event. Postgres started. We are now about to setup a
--   reconnect loop (racing with a process checker)
WaitForDB :: Event

-- | The fourth event and (possibly all subsequent events). We are looping
--   trying to successfully connect to the <tt>postgres</tt> process.
TryToConnect :: Event