Setting.hs

module Hasql.Pool.Config.Setting where

import Hasql.Connection.Settings qualified as Connection.Settings
import Hasql.Pool.Config.Config (Config)
import Hasql.Pool.Config.Config qualified as Config
import Hasql.Pool.Config.ReuseOrder (ReuseOrder (..))
import Hasql.Pool.Observation (Observation)
import Hasql.Pool.Prelude
import Hasql.Session qualified as Session

apply :: Setting -> Config -> Config
apply (Setting run) = run

-- | A single setting of a config.
newtype Setting
  = Setting (Config -> Config)

-- | Pool size.
--
-- 3 by default.
size :: Int -> Setting
size x =
  Setting (\config -> config {Config.size = x})

-- | Connection acquisition timeout.
--
-- 10 seconds by default.
acquisitionTimeout :: DiffTime -> Setting
acquisitionTimeout x =
  Setting (\config -> config {Config.acquisitionTimeout = x})

-- | 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
agingTimeout x =
  Setting (\config -> config {Config.agingTimeout = x})

-- | Maximal connection idle time.
--
-- How long to keep a connection open when it's not being used.
--
-- 10 minutes by default.
idlenessTimeout :: DiffTime -> Setting
idlenessTimeout x =
  Setting (\config -> config {Config.idlenessTimeout = x})

-- | Connection string.
--
-- By default it is:
--
-- > "postgresql://postgres:postgres@localhost:5432/postgres"
staticConnectionSettings :: Connection.Settings.Settings -> Setting
staticConnectionSettings x =
  Setting (\config -> config {Config.connectionSettingsProvider = pure x})

-- | Action providing connection settings.
--
-- Gets used each time a connection gets established by the pool.
-- This may be useful for some authorization models.
--
-- By default it is:
--
-- > pure "postgresql://postgres:postgres@localhost:5432/postgres"
dynamicConnectionSettings :: IO Connection.Settings.Settings -> Setting
dynamicConnectionSettings x =
  Setting (\config -> config {Config.connectionSettingsProvider = x})

-- | Observation handler.
--
-- Typically it's used for monitoring the state of the pool via metrics and logging.
--
-- An observation handler must not throw. Synchronous exceptions from it are discarded; asynchronous exceptions are honored. Its failure never affects the session result or the pool's state.
--
-- 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 @'atomically' . 'writeTBQueue' yourQueue@, then reading from it and processing can be done on a separate thread.
--
-- By default it is:
--
-- > const (pure ())
observationHandler :: (Observation -> IO ()) -> Setting
observationHandler x =
  Setting (\config -> config {Config.observationHandler = x})

-- | Initial session.
--
-- Gets executed on every connection upon acquisition.
-- Lets you specify the connection-wide settings.
--
-- E.g., you can set the search path for all the sessions executed by the pool by executing the following:
--
-- > initSession (Session.sql "SET search_path TO schema1, schema2, public;")
initSession :: Session.Session () -> Setting
initSession x =
  Setting (\config -> config {Config.initSession = x})

-- | Which of the idle connections a pool request gets.
--
-- With 'LIFO', the pool shrinks to the connections the load needs: the rest
-- time out as idle (see 'idlenessTimeout'). With 'FIFO', steady load keeps
-- every connection open.
--
-- 'FIFO' by default.
reuseOrder :: ReuseOrder -> Setting
reuseOrder x =
  Setting (\config -> config {Config.reuseOrder = x})