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


-- | Pool of connections for Hasql
--   
--   Pool of connections for Hasql
@package hasql-pool
@version 1


-- | Interface for processing observations of the status of the pool.
--   
--   Provides a flexible mechanism for monitoring the healthiness of the
--   pool via logs and metrics without any opinionated choices on the
--   actual monitoring technologies. Specific interpreters are encouraged
--   to be created as extension libraries.
module Hasql.Pool.Observation

-- | An observation of a change of the state of a pool.
data Observation

-- | Status of one of the pool's connections has changed.
ConnectionObservation :: UUID -> ConnectionStatus -> Observation

-- | Status of a connection.
data ConnectionStatus

-- | Connection is being established.
--   
--   This is the initial status of every connection.
ConnectingConnectionStatus :: ConnectionStatus

-- | Connection is established and not occupied.
ReadyForUseConnectionStatus :: ConnectionStatus

-- | Is being used by some session.
--   
--   After it's done the status will transition to
--   <a>ReadyForUseConnectionStatus</a> or
--   <a>TerminatedConnectionStatus</a>.
InUseConnectionStatus :: ConnectionStatus

-- | Connection terminated.
TerminatedConnectionStatus :: ConnectionTerminationReason -> ConnectionStatus

-- | Explanation of why a connection was terminated.
data ConnectionTerminationReason

-- | The age timeout of the connection has passed.
AgingConnectionTerminationReason :: ConnectionTerminationReason

-- | The timeout of how long a connection may remain idle in the pool has
--   passed.
IdlenessConnectionTerminationReason :: ConnectionTerminationReason

-- | Connectivity issues with the server.
NetworkErrorConnectionTerminationReason :: Maybe Text -> ConnectionTerminationReason

-- | User has invoked the <a>release</a> procedure.
ReleaseConnectionTerminationReason :: ConnectionTerminationReason
instance GHC.Classes.Eq Hasql.Pool.Observation.ConnectionTerminationReason
instance GHC.Show.Show Hasql.Pool.Observation.ConnectionTerminationReason
instance GHC.Classes.Eq Hasql.Pool.Observation.ConnectionStatus
instance GHC.Show.Show Hasql.Pool.Observation.ConnectionStatus
instance GHC.Classes.Eq Hasql.Pool.Observation.Observation
instance GHC.Show.Show Hasql.Pool.Observation.Observation


-- | DSL for construction of configs.
module Hasql.Pool.Config

-- | Configufation for Hasql connection pool.
data Config

-- | Compile config from a list of settings. Latter settings override the
--   preceding in cases of conflicts.
settings :: [Setting] -> Config

-- | A single setting of a config.
data Setting

-- | Pool size.
--   
--   3 by default.
size :: Int -> Setting

-- | Connection acquisition timeout.
--   
--   10 seconds by default.
acquisitionTimeout :: DiffTime -> Setting

-- | Maximal connection lifetime.
--   
--   Determines how long is available for reuse. After the timeout passes
--   and an active session is finished the connection will be closed
--   releasing a slot in the pool for a fresh connection to be established.
--   
--   This is useful as a healthy measure for resetting the server-side
--   caches.
--   
--   1 day by default.
agingTimeout :: DiffTime -> Setting

-- | Maximal connection idle time.
--   
--   How long to keep a connection open when it's not being used.
--   
--   10 minutes by default.
idlenessTimeout :: DiffTime -> Setting

-- | Connection string.
--   
--   You can use <a>settings</a> to construct it.
--   
--   <tt>"postgresql://postgres:postgres</tt>localhost:5432/postgres"@ by
--   default.
staticConnectionSettings :: Settings -> Setting

-- | Action providing connection settings.
--   
--   Gets used each time a connection gets established by the pool. This
--   may be useful for some authorization models.
--   
--   You can use <a>settings</a> to construct it.
--   
--   <tt>pure "postgresql://postgres:postgres</tt>localhost:5432/postgres"@
--   by default.
dynamicConnectionSettings :: IO Settings -> Setting

-- | Observation handler.
--   
--   Typically it's used for monitoring the state of the pool via metrics
--   and logging.
--   
--   If the provided action is not lightweight, it's recommended to use
--   intermediate bufferring via channels like TBQueue to avoid occupying
--   the pool management thread for too long. E.g., if the action is
--   <tt><a>atomically</a> . <a>writeTBQueue</a> yourQueue</tt>, then
--   reading from it and processing can be done on a separate thread.
--   
--   <tt>const (pure ())</tt> by default.
observationHandler :: (Observation -> IO ()) -> Setting

module Hasql.Pool

-- | Pool of connections to DB.
data Pool

-- | Create a connection-pool.
--   
--   No connections actually get established by this function. It is
--   delegated to <a>use</a>.
acquire :: Config -> IO Pool

-- | Use a connection from the pool to run a session and return the
--   connection to the pool, when finished.
--   
--   Session failing with a <a>ClientError</a> gets interpreted as a loss
--   of connection. In such case the connection does not get returned to
--   the pool and a slot gets freed up for a new connection to be
--   established the next time one is needed. The error still gets returned
--   from this function.
--   
--   <b>Warning:</b> Due to the mechanism mentioned above you should avoid
--   intercepting this error type from within sessions.
use :: Pool -> Session a -> IO (Either UsageError a)

-- | Release all the idle connections in the pool, and mark the in-use
--   connections to be released after use. Any connections acquired after
--   the call will be freshly established.
--   
--   The pool remains usable after this action. So you can use this
--   function to reset the connections in the pool. Naturally, you can also
--   use it to release the resources.
release :: Pool -> IO ()

-- | Union over all errors that <a>use</a> can result in.
data UsageError

-- | Attempt to establish a connection failed.
ConnectionUsageError :: ConnectionError -> UsageError

-- | Session execution failed.
SessionUsageError :: QueryError -> UsageError

-- | Timeout acquiring a connection.
AcquisitionTimeoutUsageError :: UsageError
instance GHC.Classes.Eq Hasql.Pool.UsageError
instance GHC.Show.Show Hasql.Pool.UsageError
instance GHC.Exception.Type.Exception Hasql.Pool.UsageError