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


-- | Start and stop a temporary postgres
--   
--   <tt>tmp-postgres</tt> provides functions creating a temporary
--   <tt>postgres</tt> instance.
--   
--   By default it will create a temporary directory for the data, a random
--   port for listening and a temporary directory for a UNIX domain socket.
--   
--   Here is an example using the expection safe <a>with</a> function:
--   
--   <pre>
--   with $ \db -&gt; bracket (connectPostgreSQL (toConnectionString db)) close $ \conn -&gt;
--    execute_ conn "CREATE TABLE foo (id int)"
--   </pre>
--   
--   MacOS and Linux are support. Windows is not.
--   
--   Requires PostgreSQL 9.3+
--   
--   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>
@package tmp-postgres
@version 1.7.0.1


-- | 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
StartPostgres :: Event
WaitForDB :: Event
StartPlan :: String -> Event
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 :: ExitCode -> StartError

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

-- | The <a>PartialPlan</a> was missing info and a complete <a>Plan</a>
--   could not be created.
CompletePlanFailed :: String -> [String] -> 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>ProcessConfig</a> contains the configuration necessary for starting
--   a process. It is essentially a stripped down <a>CreateProcess</a>.
data ProcessConfig
ProcessConfig :: [(String, String)] -> [String] -> Handle -> Handle -> Handle -> ProcessConfig

-- | Environment variables
[processConfigEnvVars] :: ProcessConfig -> [(String, String)]

-- | Command line arguements
[processConfigCmdLine] :: ProcessConfig -> [String]

-- | The <a>Handle</a> for standard input
[processConfigStdIn] :: ProcessConfig -> Handle

-- | The <a>Handle</a> for standard output
[processConfigStdOut] :: ProcessConfig -> Handle

-- | The <a>Handle</a> for standard error
[processConfigStdErr] :: ProcessConfig -> Handle

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

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

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

-- | The process config for <tt>postgres</tt>
[postgresPlanProcessConfig] :: PostgresPlan -> ProcessConfig

-- | Connection options. Used to verify that <tt>postgres</tt> is ready.
[postgresPlanClientOptions] :: PostgresPlan -> 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 :: 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 :: Logger -> PostgresPlan -> IO PostgresProcess

-- | <a>Plan</a> is the low level configuration necessary for creating a
--   database 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 ProcessConfig -> Maybe ProcessConfig -> PostgresPlan -> String -> FilePath -> Plan
[planLogger] :: Plan -> Logger
[planInitDb] :: Plan -> Maybe ProcessConfig
[planCreateDb] :: Plan -> Maybe ProcessConfig
[planPostgres] :: Plan -> PostgresPlan
[planConfig] :: Plan -> String
[planDataDirectory] :: Plan -> FilePath

-- | <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.StartError
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 GHC.Show.Show 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.PostgresProcess
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Core.PostgresPlan
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Core.ProcessConfig
instance GHC.Exception.Type.Exception Database.Postgres.Temp.Internal.Core.StartError


-- | 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>PartialProcessConfig</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.Partial

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

-- | Combine the current environment (if indicated by
--   <a>partialEnvVarsInherit</a>) with <a>partialEnvVarsSpecific</a>
completePartialEnvVars :: [(String, String)] -> PartialEnvVars -> Either [String] [(String, String)]

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

-- | Arguments 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.
[partialCommandLineArgsKeyBased] :: PartialCommandLineArgs -> Map String (Maybe String)

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

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

-- | The monoidial version of <a>ProcessConfig</a>. Used to combine
--   overrides with defaults when creating a <a>ProcessConfig</a>.
data PartialProcessConfig
PartialProcessConfig :: PartialEnvVars -> PartialCommandLineArgs -> Last Handle -> Last Handle -> Last Handle -> PartialProcessConfig

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

-- | A monoid for combine command line arguments or replacing them
[partialProcessConfigCmdLine] :: PartialProcessConfig -> PartialCommandLineArgs

-- | A monoid for configuring the standard input <a>Handle</a>
[partialProcessConfigStdIn] :: PartialProcessConfig -> Last Handle

-- | A monoid for configuring the standard output <a>Handle</a>
[partialProcessConfigStdOut] :: PartialProcessConfig -> Last Handle

-- | A monoid for configuring the standard error <a>Handle</a>
[partialProcessConfigStdErr] :: PartialProcessConfig -> 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 :: PartialProcessConfig

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

-- | A type to track whether a file is temporary and needs to be cleaned
--   up.
data DirectoryType
Permanent :: FilePath -> DirectoryType
Temporary :: FilePath -> DirectoryType

-- | Get the file path of a <a>DirectoryType</a>, regardless if it is a
--   <a>Permanent</a> or <a>Temporary</a> type.
toFilePath :: DirectoryType -> FilePath

-- | The monoidial version of <a>DirectoryType</a>. Used to combine
--   overrides with defaults when creating a <a>DirectoryType</a>. The
--   monoid instance treats <a>PTemporary</a> as <a>mempty</a> and takes
--   the last <a>PPermanent</a> value.
data PartialDirectoryType

-- | A permanent file that should not be generated.
PPermanent :: FilePath -> PartialDirectoryType

-- | A temporary file that needs to generated.
PTemporary :: PartialDirectoryType

-- | Either create a<a>Temporary</a> directory or do nothing to a
--   <a>Permanent</a> one.
setupDirectoryType :: String -> PartialDirectoryType -> IO DirectoryType

-- | Either remove a <a>Temporary</a> directory or do nothing to a
--   <a>Permanent</a> one.
cleanupDirectoryType :: DirectoryType -> IO ()

-- | A type for configuring the listening address of the <tt>postgres</tt>
--   process. <tt>postgres</tt> can listen on several types of sockets
--   simulatanously but we don't support that behavior. One can either
--   listen on a IP based socket or a UNIX domain socket.
data SocketClass

-- | IP socket type. The <a>String</a> is either an IP address or a host
--   that will resolve to an IP address.
IpSocket :: String -> SocketClass

-- | UNIX domain socket
UnixSocket :: DirectoryType -> SocketClass

-- | Create the extra config lines for listening based on the
--   <a>SocketClass</a>
socketClassToConfig :: SocketClass -> [String]

-- | Many processes require a "host" flag. We can generate one from the
--   <a>SocketClass</a>.
socketClassToHostFlag :: SocketClass -> [(String, Maybe String)]

-- | Get the IP address, host name or UNIX domain socket directory as a
--   <a>String</a>
socketClassToHost :: SocketClass -> String

-- | The monoidial version of <a>SocketClass</a>. Used to combine overrides
--   with defaults when creating a <a>SocketClass</a>. The monoid instance
--   treats 'PUnixSocket mempty' as <a>mempty</a> and combines the
data PartialSocketClass

-- | The monoid for combining IP address configuration
PIpSocket :: Last String -> PartialSocketClass

-- | The monoid for combining UNIX socket configuration
PUnixSocket :: PartialDirectoryType -> PartialSocketClass

-- | Turn a <a>PartialSocketClass</a> to a <a>SocketClass</a>. If the
--   <a>PIpSocket</a> is <a>Nothing</a> default to "127.0.0.1". If the is a
--   <a>PUnixSocket</a> optionally create a temporary directory if
--   configured to do so.
setupPartialSocketClass :: PartialSocketClass -> IO SocketClass

-- | Cleanup the UNIX socket temporary directory if one was created.
cleanupSocketConfig :: SocketClass -> IO ()

-- | PartialPostgresPlan
data PartialPostgresPlan
PartialPostgresPlan :: PartialProcessConfig -> Options -> PartialPostgresPlan

-- | Monoid for the <tt>postgres</tt> ProcessConfig.
[partialPostgresPlanProcessConfig] :: PartialPostgresPlan -> PartialProcessConfig

-- | Monoid for the <tt>postgres</tt> client connection options.
[partialPostgresPlanClientConfig] :: PartialPostgresPlan -> Options

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

-- | The monoidial version of <a>Plan</a>. Used to combine overrides with
--   defaults when creating a plan.
data PartialPlan
PartialPlan :: Last Logger -> Maybe PartialProcessConfig -> Maybe PartialProcessConfig -> PartialPostgresPlan -> [String] -> Last String -> PartialPlan
[partialPlanLogger] :: PartialPlan -> Last Logger
[partialPlanInitDb] :: PartialPlan -> Maybe PartialProcessConfig
[partialPlanCreateDb] :: PartialPlan -> Maybe PartialProcessConfig
[partialPlanPostgres] :: PartialPlan -> PartialPostgresPlan
[partialPlanConfig] :: PartialPlan -> [String]
[partialPlanDataDirectory] :: PartialPlan -> Last String

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

-- | <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 -> SocketClass -> DirectoryType -> Resources

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

-- | The <a>SocketClass</a>. Used to track if a temporary directory was
--   made as the socket location.
[resourcesSocket] :: Resources -> SocketClass

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

-- | The high level options for overriding default behavior.
data Config
Config :: PartialPlan -> PartialSocketClass -> PartialDirectoryType -> Last (Maybe Int) -> Config

-- | Extend or replace any of the configuration used to create a final
--   <a>Plan</a>
[configPlan] :: Config -> PartialPlan

-- | Override the default <a>SocketClass</a> by setting this.
[configSocket] :: Config -> PartialSocketClass

-- | Override the default temporary data directory by passing in 'Permanent
--   DIRECTORY'
[configDataDir] :: Config -> PartialDirectoryType

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

-- | Create a <a>PartialPlan</a> that sets the command line options of all
--   processes (<tt>initdb</tt>, <tt>postgres</tt> and <tt>createdb</tt>)
--   using a
toPlan :: Bool -> Bool -> Int -> SocketClass -> FilePath -> PartialPlan

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

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

-- | 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.Partial.Config
instance GHC.Base.Semigroup Database.Postgres.Temp.Internal.Partial.Config
instance GHC.Generics.Generic Database.Postgres.Temp.Internal.Partial.Config
instance GHC.Base.Monoid Database.Postgres.Temp.Internal.Partial.PartialPlan
instance GHC.Base.Semigroup Database.Postgres.Temp.Internal.Partial.PartialPlan
instance GHC.Generics.Generic Database.Postgres.Temp.Internal.Partial.PartialPlan
instance GHC.Base.Monoid Database.Postgres.Temp.Internal.Partial.PartialPostgresPlan
instance GHC.Base.Semigroup Database.Postgres.Temp.Internal.Partial.PartialPostgresPlan
instance GHC.Generics.Generic Database.Postgres.Temp.Internal.Partial.PartialPostgresPlan
instance GHC.Generics.Generic Database.Postgres.Temp.Internal.Partial.PartialSocketClass
instance GHC.Classes.Ord Database.Postgres.Temp.Internal.Partial.PartialSocketClass
instance GHC.Classes.Eq Database.Postgres.Temp.Internal.Partial.PartialSocketClass
instance GHC.Show.Show Database.Postgres.Temp.Internal.Partial.PartialSocketClass
instance GHC.Generics.Generic Database.Postgres.Temp.Internal.Partial.SocketClass
instance GHC.Classes.Ord Database.Postgres.Temp.Internal.Partial.SocketClass
instance GHC.Classes.Eq Database.Postgres.Temp.Internal.Partial.SocketClass
instance GHC.Show.Show Database.Postgres.Temp.Internal.Partial.SocketClass
instance GHC.Classes.Ord Database.Postgres.Temp.Internal.Partial.PartialDirectoryType
instance GHC.Classes.Eq Database.Postgres.Temp.Internal.Partial.PartialDirectoryType
instance GHC.Show.Show Database.Postgres.Temp.Internal.Partial.PartialDirectoryType
instance GHC.Classes.Ord Database.Postgres.Temp.Internal.Partial.DirectoryType
instance GHC.Classes.Eq Database.Postgres.Temp.Internal.Partial.DirectoryType
instance GHC.Show.Show Database.Postgres.Temp.Internal.Partial.DirectoryType
instance GHC.Base.Monoid Database.Postgres.Temp.Internal.Partial.PartialProcessConfig
instance GHC.Base.Semigroup Database.Postgres.Temp.Internal.Partial.PartialProcessConfig
instance GHC.Show.Show Database.Postgres.Temp.Internal.Partial.PartialProcessConfig
instance GHC.Classes.Eq Database.Postgres.Temp.Internal.Partial.PartialProcessConfig
instance GHC.Generics.Generic Database.Postgres.Temp.Internal.Partial.PartialProcessConfig
instance GHC.Base.Monoid Database.Postgres.Temp.Internal.Partial.PartialCommandLineArgs
instance GHC.Classes.Eq Database.Postgres.Temp.Internal.Partial.PartialCommandLineArgs
instance GHC.Show.Show Database.Postgres.Temp.Internal.Partial.PartialCommandLineArgs
instance GHC.Generics.Generic Database.Postgres.Temp.Internal.Partial.PartialCommandLineArgs
instance GHC.Classes.Eq Database.Postgres.Temp.Internal.Partial.PartialEnvVars
instance GHC.Show.Show Database.Postgres.Temp.Internal.Partial.PartialEnvVars
instance GHC.Generics.Generic Database.Postgres.Temp.Internal.Partial.PartialEnvVars
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Partial.Config
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Partial.Resources
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Partial.PartialPlan
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Partial.PartialPostgresPlan
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Partial.PartialSocketClass
instance GHC.Base.Semigroup Database.Postgres.Temp.Internal.Partial.PartialSocketClass
instance GHC.Base.Monoid Database.Postgres.Temp.Internal.Partial.PartialSocketClass
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Partial.SocketClass
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Partial.PartialDirectoryType
instance GHC.Base.Semigroup Database.Postgres.Temp.Internal.Partial.PartialDirectoryType
instance GHC.Base.Monoid Database.Postgres.Temp.Internal.Partial.PartialDirectoryType
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Partial.DirectoryType
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Partial.PartialProcessConfig
instance GHC.Base.Semigroup Database.Postgres.Temp.Internal.Partial.PartialCommandLineArgs
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Partial.PartialCommandLineArgs
instance GHC.Base.Semigroup Database.Postgres.Temp.Internal.Partial.PartialEnvVars
instance GHC.Base.Monoid Database.Postgres.Temp.Internal.Partial.PartialEnvVars
instance Text.PrettyPrint.ANSI.Leijen.Internal.Pretty Database.Postgres.Temp.Internal.Partial.PartialEnvVars


-- | 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 postgres connection information. The <a>DB</a> also
--   includes the final <a>Plan</a> that was used to start <tt>initdb</tt>,
--   <tt>createdb</tt> and <tt>postgres</tt>. See <a>toConnectionString</a>
--   for converting a <a>DB</a> to postgresql connection string.
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

-- | Default postgres options
defaultPostgresConfig :: [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 on a random port. Additionally it will use append the
--   following onto the "postgresql.conf"
--   
--   <pre>
--   shared_buffers = 12MB
--   fsync = off
--   synchronous_commit = off
--   full_page_writes = off
--   log_min_duration_statement = 0
--   log_connections = on
--   log_disconnections = on
--   client_min_messages = ERROR
--   </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>.
--   
--   <a>defaultConfig</a> also sets the <a>partialPlanInitDb</a> to
--   <a>pure</a> <a>standardProcessConfig</a> and
--   <a>partialPostgresPlanProcessConfig</a> to
--   <a>standardProcessConfig</a>.
defaultConfig :: Config

-- | <a>mappend</a> the <a>defaultConfig</a> with a <a>Config</a> that
--   provides additional "postgresql.conf" lines. Equivalent to
--   
--   <pre>
--   defaultPostgresConf extra = defaultConfig &lt;&gt; mempty
--     { configPlan = mempty
--       { partialPlanConfig = extra
--       }
--     }
--   </pre>
defaultPostgresConf :: [String] -> Config

-- | Create temporary resources and use them to make a <a>Config</a>. The
--   generated <a>Config</a> is combined with the passed in
--   <tt>extraConfiguration</tt> to create a <a>Plan</a> that is used to
--   create a database. The output <a>DB</a> includes references to the
--   temporary resources for cleanup and the final plan that was used to
--   generate the database and processes
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
--   directories 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

-- | Restart the <tt>postgres</tt> using the <a>Plan</a> from the <a>DB</a>
--   (e.g. <tt>resourcesPlan . dbResources</tt>)
restart :: DB -> IO (Either StartError DB)

-- | Reload the configuration file without shutting down. Calls
--   <tt>pg_reload_conf()</tt>.
reloadConfig :: DB -> IO ()

-- | Exception safe default database create. Takes an <tt>action</tt>
--   continuation which is given a <a>DB</a> it can use to connect to (see
--   <a>toConnectionString</a> or <a>postgresProcessClientOptions</a>). All
--   of the database resources are automatically cleaned up on completion
--   even in the face of exceptions.
withConfig :: Config -> (DB -> IO a) -> IO (Either StartError a)

-- | Default expectation safe interface. Equivalent to <a>withConfig</a>
--   the <a>defaultConfig</a>
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>Config</a>.
prettyPrintConfig :: Config -> String

-- | Display a <a>DB</a>
prettyPrintDB :: DB -> String
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.
--   
--   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 (optionally) <tt>initdb</tt>,
--   <tt>postgres</tt> and (optionally) <tt>createdb</tt>. All of the
--   command line, environment variables and configuration files that are
--   generated by default for the respective executables can be extended or
--   overrided.
--   
--   In general <tt>tmp-postgres</tt> is useful if you want a temporary
--   <tt>postgres</tt> which will not clash with open ports. Here are some
--   different use cases for <tt>tmp-postgres</tt> and there 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>
--   
--   The level of custom configuration is extensive but with great power
--   comes the ability to screw everything up. <tt>tmp-postgres</tt>
--   doesn't validate any custom configuration and one can easily create a
--   <a>Config</a> that would not allow <tt>postgres</tt> to start.
--   
--   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 <a>withConfig</a>
--   the <a>defaultConfig</a>
with :: (DB -> IO a) -> IO (Either StartError a)

-- | Exception safe default database create. Takes an <tt>action</tt>
--   continuation which is given a <a>DB</a> it can use to connect to (see
--   <a>toConnectionString</a> or <a>postgresProcessClientOptions</a>). All
--   of the database resources are automatically cleaned up on completion
--   even in the face of exceptions.
withConfig :: Config -> (DB -> IO a) -> IO (Either StartError a)

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

-- | Create temporary resources and use them to make a <a>Config</a>. The
--   generated <a>Config</a> is combined with the passed in
--   <tt>extraConfiguration</tt> to create a <a>Plan</a> that is used to
--   create a database. The output <a>DB</a> includes references to the
--   temporary resources for cleanup and the final plan that was used to
--   generate the database and processes
startConfig :: Config -> IO (Either StartError DB)

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

-- | 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 on a random port. Additionally it will use append the
--   following onto the "postgresql.conf"
--   
--   <pre>
--   shared_buffers = 12MB
--   fsync = off
--   synchronous_commit = off
--   full_page_writes = off
--   log_min_duration_statement = 0
--   log_connections = on
--   log_disconnections = on
--   client_min_messages = ERROR
--   </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>.
--   
--   <a>defaultConfig</a> also sets the <a>partialPlanInitDb</a> to
--   <a>pure</a> <a>standardProcessConfig</a> and
--   <a>partialPostgresPlanProcessConfig</a> to
--   <a>standardProcessConfig</a>.
defaultConfig :: Config

-- | <a>mappend</a> the <a>defaultConfig</a> with a <a>Config</a> that
--   provides additional "postgresql.conf" lines. Equivalent to
--   
--   <pre>
--   defaultPostgresConf extra = defaultConfig &lt;&gt; mempty
--     { configPlan = mempty
--       { partialPlanConfig = extra
--       }
--     }
--   </pre>
defaultPostgresConf :: [String] -> Config

-- | 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 :: PartialProcessConfig

-- | 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

-- | Restart the <tt>postgres</tt> using the <a>Plan</a> from the <a>DB</a>
--   (e.g. <tt>resourcesPlan . dbResources</tt>)
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

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

-- | Reload the configuration file without shutting down. Calls
--   <tt>pg_reload_conf()</tt>.
reloadConfig :: DB -> IO ()

-- | 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 :: ExitCode -> StartError

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

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

-- | Handle for holding temporary resources, the <tt>postgres</tt> process
--   handle and postgres connection information. The <a>DB</a> also
--   includes the final <a>Plan</a> that was used to start <tt>initdb</tt>,
--   <tt>createdb</tt> and <tt>postgres</tt>. See <a>toConnectionString</a>
--   for converting a <a>DB</a> to postgresql connection string.
data DB

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

-- | 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

-- | The high level options for overriding default behavior.
data Config
Config :: PartialPlan -> PartialSocketClass -> PartialDirectoryType -> Last (Maybe Int) -> Config

-- | Extend or replace any of the configuration used to create a final
--   <a>Plan</a>
[configPlan] :: Config -> PartialPlan

-- | Override the default <a>SocketClass</a> by setting this.
[configSocket] :: Config -> PartialSocketClass

-- | Override the default temporary data directory by passing in 'Permanent
--   DIRECTORY'
[configDataDir] :: Config -> PartialDirectoryType

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

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

-- | A type to track whether a file is temporary and needs to be cleaned
--   up.
data DirectoryType
Permanent :: FilePath -> DirectoryType
Temporary :: FilePath -> DirectoryType

-- | The monoidial version of <a>DirectoryType</a>. Used to combine
--   overrides with defaults when creating a <a>DirectoryType</a>. The
--   monoid instance treats <a>PTemporary</a> as <a>mempty</a> and takes
--   the last <a>PPermanent</a> value.
data PartialDirectoryType

-- | A permanent file that should not be generated.
PPermanent :: FilePath -> PartialDirectoryType

-- | A temporary file that needs to generated.
PTemporary :: PartialDirectoryType

-- | A type for configuring the listening address of the <tt>postgres</tt>
--   process. <tt>postgres</tt> can listen on several types of sockets
--   simulatanously but we don't support that behavior. One can either
--   listen on a IP based socket or a UNIX domain socket.
data SocketClass

-- | IP socket type. The <a>String</a> is either an IP address or a host
--   that will resolve to an IP address.
IpSocket :: String -> SocketClass

-- | UNIX domain socket
UnixSocket :: DirectoryType -> SocketClass

-- | The monoidial version of <a>SocketClass</a>. Used to combine overrides
--   with defaults when creating a <a>SocketClass</a>. The monoid instance
--   treats 'PUnixSocket mempty' as <a>mempty</a> and combines the
data PartialSocketClass

-- | The monoid for combining IP address configuration
PIpSocket :: Last String -> PartialSocketClass

-- | The monoid for combining UNIX socket configuration
PUnixSocket :: PartialDirectoryType -> PartialSocketClass

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

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

-- | Arguments 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.
[partialCommandLineArgsKeyBased] :: PartialCommandLineArgs -> Map String (Maybe String)

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

-- | The monoidial version of <a>ProcessConfig</a>. Used to combine
--   overrides with defaults when creating a <a>ProcessConfig</a>.
data PartialProcessConfig
PartialProcessConfig :: PartialEnvVars -> PartialCommandLineArgs -> Last Handle -> Last Handle -> Last Handle -> PartialProcessConfig

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

-- | A monoid for combine command line arguments or replacing them
[partialProcessConfigCmdLine] :: PartialProcessConfig -> PartialCommandLineArgs

-- | A monoid for configuring the standard input <a>Handle</a>
[partialProcessConfigStdIn] :: PartialProcessConfig -> Last Handle

-- | A monoid for configuring the standard output <a>Handle</a>
[partialProcessConfigStdOut] :: PartialProcessConfig -> Last Handle

-- | A monoid for configuring the standard error <a>Handle</a>
[partialProcessConfigStdErr] :: PartialProcessConfig -> Last Handle

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

-- | Environment variables
[processConfigEnvVars] :: ProcessConfig -> [(String, String)]

-- | Command line arguements
[processConfigCmdLine] :: ProcessConfig -> [String]

-- | The <a>Handle</a> for standard input
[processConfigStdIn] :: ProcessConfig -> Handle

-- | The <a>Handle</a> for standard output
[processConfigStdOut] :: ProcessConfig -> Handle

-- | The <a>Handle</a> for standard error
[processConfigStdErr] :: ProcessConfig -> Handle

-- | PartialPostgresPlan
data PartialPostgresPlan
PartialPostgresPlan :: PartialProcessConfig -> Options -> PartialPostgresPlan

-- | Monoid for the <tt>postgres</tt> ProcessConfig.
[partialPostgresPlanProcessConfig] :: PartialPostgresPlan -> PartialProcessConfig

-- | Monoid for the <tt>postgres</tt> client connection options.
[partialPostgresPlanClientConfig] :: PartialPostgresPlan -> Options

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

-- | The process config for <tt>postgres</tt>
[postgresPlanProcessConfig] :: PostgresPlan -> ProcessConfig

-- | Connection options. Used to verify that <tt>postgres</tt> is ready.
[postgresPlanClientOptions] :: PostgresPlan -> 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

-- | The monoidial version of <a>Plan</a>. Used to combine overrides with
--   defaults when creating a plan.
data PartialPlan
PartialPlan :: Last Logger -> Maybe PartialProcessConfig -> Maybe PartialProcessConfig -> PartialPostgresPlan -> [String] -> Last String -> PartialPlan
[partialPlanLogger] :: PartialPlan -> Last Logger
[partialPlanInitDb] :: PartialPlan -> Maybe PartialProcessConfig
[partialPlanCreateDb] :: PartialPlan -> Maybe PartialProcessConfig
[partialPlanPostgres] :: PartialPlan -> PartialPostgresPlan
[partialPlanConfig] :: PartialPlan -> [String]
[partialPlanDataDirectory] :: PartialPlan -> Last String

-- | <a>Plan</a> is the low level configuration necessary for creating a
--   database 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 ProcessConfig -> Maybe ProcessConfig -> PostgresPlan -> String -> FilePath -> Plan
[planLogger] :: Plan -> Logger
[planInitDb] :: Plan -> Maybe ProcessConfig
[planCreateDb] :: Plan -> Maybe ProcessConfig
[planPostgres] :: Plan -> PostgresPlan
[planConfig] :: Plan -> String
[planDataDirectory] :: Plan -> FilePath