-- 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.0.1.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>initPlan</a> for more details.
module Database.Postgres.Temp.Internal.Core

-- | Internal events for debugging
data Event
StartPostgres :: Event
WaitForDB :: 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] -> 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 :: 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

-- | PostgresPlan 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.
[postgresPlanClientConfig] :: PostgresPlan -> Options

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

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

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

-- | Force all connections to the database to close. Can be useful in some
--   testing situations. Called during shutdown as well.
terminateConnections :: Options -> IO ()

-- | 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
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 simple helper to throw <a>ExitCode</a>s when they are
--   <a>ExitFailure</a>.
throwIfNotSuccess :: Exception e => (ExitCode -> e) -> ExitCode -> IO ()

-- | <a>initPlan</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.
initPlan :: Plan -> IO PostgresProcess

-- | Stop the <tt>postgres</tt> process. See <a>stopPostgresProcess</a> for
--   more details.
shutdownPlan :: 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 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 three classes of types. Types like <a>Lastoid</a> that
--   are generic and could live in a module like "base".
--   
--   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>startWith</a> and related functions. |
module Database.Postgres.Temp.Internal.Partial

-- | <a>Lastoid</a> is helper for overriding configuration values. It's
--   <a>Semigroup</a> instance let's one either combine the <tt>a</tt> of
--   two <a>Lastoid</a>s using <a>&lt;&gt;</a> via the <a>Mappend</a>
--   constructor or one can wholly replace the value with the last value
--   using the <a>Replace</a> constructor. Roughly
--   
--   <pre>
--   x &lt;&gt; Replace y = Replace y
--   Replace x &lt;&gt; Mappend y = Replace (x &lt;&gt; y)
--   Mappend x &lt;&gt; Mappend y = Mappend (x &lt;&gt; y)
--   </pre>
data Lastoid a
Replace :: a -> Lastoid a
Mappend :: a -> Lastoid a

-- | Get the value of a <a>Lastoid</a> regardless if it is a <a>Replace</a>
--   or a <a>Mappend</a>.
getLastoid :: Lastoid a -> a

-- | The monoidial version of <a>ProcessConfig</a>. Used to combine
--   overrides with defaults when creating a <a>ProcessConfig</a>.
data PartialProcessConfig
PartialProcessConfig :: Lastoid [(String, String)] -> Lastoid [String] -> Last Handle -> Last Handle -> Last Handle -> PartialProcessConfig

-- | A monoid for combine environment variables or replacing them
[partialProcessConfigEnvVars] :: PartialProcessConfig -> Lastoid [(String, String)]

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

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

-- | A helper to add more info to all the error messages.
addErrorContext :: String -> Either [String] a -> Either [String] a

-- | A helper for creating an error if a <a>Last</a> is not defined.
getOption :: String -> Last a -> Validation [String] a

-- | Turn a <a>PartialProcessConfig</a> into a <a>ProcessConfig</a>. Fails
--   if any values are missing.
completeProcessConfig :: 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.
initDirectoryType :: String -> PartialDirectoryType -> IO DirectoryType

-- | Either create a temporary directory or do nothing
rmDirIgnoreErrors :: FilePath -> IO ()

-- | Either remove a <a>Temporary</a> directory or do nothing to a
--   <a>Permanent</a> one.
shutdownDirectoryType :: 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]

-- | 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.
initPartialSocketClass :: PartialSocketClass -> IO SocketClass

-- | Cleanup the UNIX socket temporary directory if one was created.
shutdownSocketConfig :: 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 :: 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 -> Lastoid (Maybe PartialProcessConfig) -> Lastoid (Maybe PartialProcessConfig) -> PartialPostgresPlan -> Lastoid [String] -> Last String -> PartialPlan
[partialPlanLogger] :: PartialPlan -> Last Logger
[partialPlanInitDb] :: PartialPlan -> Lastoid (Maybe PartialProcessConfig)
[partialPlanCreateDb] :: PartialPlan -> Lastoid (Maybe PartialProcessConfig)
[partialPlanPostgres] :: PartialPlan -> PartialPostgresPlan
[partialPlanConfig] :: PartialPlan -> Lastoid [String]
[partialPlanDataDirectory] :: PartialPlan -> Last String

-- | Turn a <a>PartialPlan</a> into a <a>Plan</a>. Fails if any values are
--   missing.
completePlan :: 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>initPlan</a>. See <a>initConfig</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>initPlan</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 :: 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.
initConfig :: Config -> IO Resources

-- | Free the temporary resources created by <a>initConfig</a>
shutdownResources :: 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
optionsToPlan :: Options -> PartialPlan
userToPlan :: Maybe String -> PartialPlan
dbnameToPlan :: Maybe String -> PartialPlan
hostToSocketClass :: Maybe String -> PartialSocketClass
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.Generics.Generic Database.Postgres.Temp.Internal.Partial.PartialProcessConfig
instance GHC.Base.Functor Database.Postgres.Temp.Internal.Partial.Lastoid
instance GHC.Classes.Eq a => GHC.Classes.Eq (Database.Postgres.Temp.Internal.Partial.Lastoid a)
instance GHC.Show.Show a => GHC.Show.Show (Database.Postgres.Temp.Internal.Partial.Lastoid a)
instance GHC.Base.Semigroup Database.Postgres.Temp.Internal.Partial.PartialSocketClass
instance GHC.Base.Monoid Database.Postgres.Temp.Internal.Partial.PartialSocketClass
instance GHC.Base.Semigroup Database.Postgres.Temp.Internal.Partial.PartialDirectoryType
instance GHC.Base.Monoid Database.Postgres.Temp.Internal.Partial.PartialDirectoryType
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Database.Postgres.Temp.Internal.Partial.Lastoid a)
instance GHC.Base.Monoid a => GHC.Base.Monoid (Database.Postgres.Temp.Internal.Partial.Lastoid 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 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>.
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 <tt>postgresProcessClientConfig .
--   dbPostgresProcess</tt>
toConnectionString :: DB -> ByteString

-- | Default postgres options
defaultPostgresConfig :: [String]

-- | The default configuration. This will create a database called "test"
--   and create a temporary directory for the data and a temporary
--   directory for a unix socket on a random port. If you would like to
--   customize this behavior you can start with the <a>defaultConfig</a>
--   and overwrite fields or combine the <a>Config</a> with another config
--   using <a>&lt;&gt;</a> (<a>mappend</a>). If you would like complete
--   control over the behavior of <tt>initdb</tt>, <tt>postgres</tt> and
--   <tt>createdb</tt> you can call the internal function <a>initPlan</a>
--   directly although this should not be necessary.
defaultConfig :: Config

-- | <a>standardConfig</a> makes a default config with
--   <a>standardProcessConfig</a>. It is used by default but can be
--   overriden by the extra config.
standardConfig :: IO 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
startWith :: Config -> IO (Either StartError DB)

-- | Default start behavior. Equivalent to calling <a>startWith</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>postgresProcessClientConfig</a>). All
--   of the database resources are automatically cleaned up on completion
--   even in the face of exceptions.
withPlan :: Config -> (DB -> IO a) -> IO (Either StartError a)

-- | Default expectation safe interface. Equivalent to <a>withPlan</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 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. This function works around a difficulty with appending options to
--   the <tt>createdb</tt> plan by mappending to <a>defaultConfig</a> and
--   optionally replacing the database name.
optionsToDefaultConfig :: Options -> Config


-- | This module 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>
--   <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>withPlan</a> (or
--   <a>startWith</a>).
--   
--   <tt>tmp-postgres</tt> ultimately calls <tt>initdb</tt>,
--   <tt>postgres</tt> and <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.
--   
--   All <tt>tmp-postgres</tt> by default is most useful for creating tests
--   by configuring "tmp-postgres" differently it can be used for other
--   purposes.
--   
--   <ul>
--   <li>By disabling <tt>initdb</tt> and <tt>createdb</tt> one could run a
--   temporary 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 ability to screw everything up. `tmp-postgres` doesn't validate
--   any custom configuration and one can easily create a <a>Config</a>
--   that would not allow postgres 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

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

-- | Default expectation safe interface. Equivalent to <a>withPlan</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>postgresProcessClientConfig</a>). All
--   of the database resources are automatically cleaned up on completion
--   even in the face of exceptions.
withPlan :: Config -> (DB -> IO a) -> IO (Either StartError a)

-- | Default start behavior. Equivalent to calling <a>startWith</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
startWith :: 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 "test"
--   and create a temporary directory for the data and a temporary
--   directory for a unix socket on a random port. If you would like to
--   customize this behavior you can start with the <a>defaultConfig</a>
--   and overwrite fields or combine the <a>Config</a> with another config
--   using <a>&lt;&gt;</a> (<a>mappend</a>). If you would like complete
--   control over the behavior of <tt>initdb</tt>, <tt>postgres</tt> and
--   <tt>createdb</tt> you can call the internal function <a>initPlan</a>
--   directly although this should not be necessary.
defaultConfig :: 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 ()

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

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

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

-- | <a>Lastoid</a> is helper for overriding configuration values. It's
--   <a>Semigroup</a> instance let's one either combine the <tt>a</tt> of
--   two <a>Lastoid</a>s using <a>&lt;&gt;</a> via the <a>Mappend</a>
--   constructor or one can wholly replace the value with the last value
--   using the <a>Replace</a> constructor. Roughly
--   
--   <pre>
--   x &lt;&gt; Replace y = Replace y
--   Replace x &lt;&gt; Mappend y = Replace (x &lt;&gt; y)
--   Mappend x &lt;&gt; Mappend y = Mappend (x &lt;&gt; y)
--   </pre>
data Lastoid a
Replace :: a -> Lastoid a
Mappend :: a -> Lastoid a

-- | 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 monoidial version of <a>ProcessConfig</a>. Used to combine
--   overrides with defaults when creating a <a>ProcessConfig</a>.
data PartialProcessConfig
PartialProcessConfig :: Lastoid [(String, String)] -> Lastoid [String] -> Last Handle -> Last Handle -> Last Handle -> PartialProcessConfig

-- | A monoid for combine environment variables or replacing them
[partialProcessConfigEnvVars] :: PartialProcessConfig -> Lastoid [(String, String)]

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

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

-- | PostgresPlan 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.
[postgresPlanClientConfig] :: PostgresPlan -> Options

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

-- | Connection options
[postgresProcessClientConfig] :: 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 -> Lastoid (Maybe PartialProcessConfig) -> Lastoid (Maybe PartialProcessConfig) -> PartialPostgresPlan -> Lastoid [String] -> Last String -> PartialPlan
[partialPlanLogger] :: PartialPlan -> Last Logger
[partialPlanInitDb] :: PartialPlan -> Lastoid (Maybe PartialProcessConfig)
[partialPlanCreateDb] :: PartialPlan -> Lastoid (Maybe PartialProcessConfig)
[partialPlanPostgres] :: PartialPlan -> PartialPostgresPlan
[partialPlanConfig] :: PartialPlan -> Lastoid [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

-- | 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. This function works around a difficulty with appending options to
--   the <tt>createdb</tt> plan by mappending to <a>defaultConfig</a> and
--   optionally replacing the database name.
optionsToDefaultConfig :: Options -> Config