Safe Haskell	None
Language	GHC2024

Arbiter.Hasql.HasqlDb

Contents

Database monad
Environment creation
Hasql settings
Exceptions

Description

The hasql database monad with a built-in MonadArbiter instance:

import Arbiter.Core qualified as Arb
import Arbiter.Hasql qualified as ArbH
import Control.Monad (void)

myFunction :: ArbH.HasqlDb MyRegistry IO ()
myFunction = void $ Arb.insertJob (Arb.defaultJob myPayload)

Synopsis

newtype HasqlDb (registry :: JobPayloadRegistry) (m :: Type -> Type) a = HasqlDb {
- unHasqlDb :: Db Connection HasqlConfig registry m a
}
type HasqlEnv = Env Connection HasqlConfig
data Db conn cfg (registry :: JobPayloadRegistry) (m :: Type -> Type) a
data Env conn cfg (registry :: JobPayloadRegistry) = Env {
- schema :: SchemaName
- poolState :: PoolState conn
- listener :: Maybe Listener
- driverConfig :: cfg
}
newtype HasqlConfig = HasqlConfig {
- preparedStatements :: Bool
}
data PoolState conn = PoolState {
- connectionPool :: Maybe (Pool conn)
- pinned :: Maybe (conn, Int)
}
class Monad m => HasPoolState conn (m :: Type -> Type) | m -> conn where
- getPoolState :: m (PoolState conn)
- localPoolState :: (PoolState conn -> PoolState conn) -> m a -> m a
runHasqlDb :: forall (registry :: JobPayloadRegistry) m a. HasqlEnv registry -> HasqlDb registry m a -> m a
inTransaction :: forall (registry :: JobPayloadRegistry) m a. Connection -> SchemaName -> HasqlDb registry m a -> m a
inTransactionWith :: forall (registry :: JobPayloadRegistry) m a. HasqlConfig -> Connection -> SchemaName -> HasqlDb registry m a -> m a
data HasqlConnect
toHasqlConnect :: Adapter -> ByteString -> HasqlConnect
acquireConnect :: HasqlConnect -> IO (Either String Connection)
createHasqlEnv :: forall (registry :: JobPayloadRegistry) m. MonadIO m => Proxy registry -> HasqlConnect -> SchemaName -> m (HasqlEnv registry)
createHasqlEnvWithConfig :: forall (registry :: JobPayloadRegistry) m. MonadIO m => Proxy registry -> HasqlConnect -> SchemaName -> PoolConfig -> m (HasqlEnv registry)
createHasqlEnvWithPool :: forall (registry :: JobPayloadRegistry) m. MonadIO m => Proxy registry -> Pool Connection -> SchemaName -> m (HasqlEnv registry)
destroyHasqlEnv :: forall m (registry :: JobPayloadRegistry). MonadIO m => HasqlEnv registry -> m ()
disableListener :: forall conn cfg (registry :: JobPayloadRegistry). Env conn cfg registry -> Env conn cfg registry
useDedicatedListener :: forall m (registry :: JobPayloadRegistry). MonadIO m => HasqlConnect -> HasqlEnv registry -> m (HasqlEnv registry)
setPreparedStatements :: forall (registry :: JobPayloadRegistry). Bool -> HasqlEnv registry -> HasqlEnv registry
type HasqlSettings = Settings
hasqlSettings :: ByteString -> HasqlSettings
newtype HasqlConnectionError = HasqlConnectionError String

Database monad

newtype HasqlDb (registry :: JobPayloadRegistry) (m :: Type -> Type) aSource #

The hasql database monad.

Constructors

HasqlDb
Fields unHasqlDb :: Db Connection HasqlConfig registry m a

Instances

Instances details

Monad m => HasPoolState Connection (HasqlDb registry m) Source #

Instance details

Defined in Arbiter.Hasql.HasqlDb

Methods

getPoolState :: HasqlDb registry m (PoolState Connection)#

localPoolState :: (PoolState Connection -> PoolState Connection) -> HasqlDb registry m a -> HasqlDb registry m a#

MonadTrans (HasqlDb registry) Source #

Instance details

Defined in Arbiter.Hasql.HasqlDb

Methods

lift :: Monad m => m a -> HasqlDb registry m a#

Monad m => MonadReader (HasqlEnv registry) (HasqlDb registry m) Source #

Instance details

Defined in Arbiter.Hasql.HasqlDb

Methods

ask :: HasqlDb registry m (HasqlEnv registry)#

local :: (HasqlEnv registry -> HasqlEnv registry) -> HasqlDb registry m a -> HasqlDb registry m a#

reader :: (HasqlEnv registry -> a) -> HasqlDb registry m a#

MonadUnliftIO m => MonadArbiter (HasqlDb registry m) Source #

Instance details

Defined in Arbiter.Hasql.HasqlDb

Associated Types

type RegistryOf (HasqlDb registry m)
Instance details Defined in Arbiter.Hasql.HasqlDb type RegistryOf (HasqlDb registry m) = registry

Methods

getSchema :: HasqlDb registry m SchemaName#

executeQuery :: Query a -> HasqlDb registry m [a]#

executeQueryPrepared :: Query a -> HasqlDb registry m [a]#

executeStatement :: Query a -> HasqlDb registry m Int64#

withDbTransaction :: HasqlDb registry m a -> HasqlDb registry m a#

runHandlerWithConnection :: JobHandler (HasqlDb registry m) payload (ResultOf (HasqlDb registry m) payload) -> JobRead payload -> HasqlDb registry m (ResultOf (HasqlDb registry m) payload)#

getListener :: HasqlDb registry m (Maybe Listener)#

MonadCatch m => MonadCatch (HasqlDb registry m) Source #

Instance details

Defined in Arbiter.Hasql.HasqlDb

Methods

catch :: (HasCallStack, Exception e) => HasqlDb registry m a -> (e -> HasqlDb registry m a) -> HasqlDb registry m a#

catchNoPropagate :: Exception e => HasqlDb registry m a -> (ExceptionWithContext e -> HasqlDb registry m a) -> HasqlDb registry m a#

MonadMask m => MonadMask (HasqlDb registry m) Source #

Instance details

Defined in Arbiter.Hasql.HasqlDb

Methods

mask :: HasCallStack => ((forall a. HasqlDb registry m a -> HasqlDb registry m a) -> HasqlDb registry m b) -> HasqlDb registry m b#

uninterruptibleMask :: HasCallStack => ((forall a. HasqlDb registry m a -> HasqlDb registry m a) -> HasqlDb registry m b) -> HasqlDb registry m b#

generalBracket :: HasCallStack => HasqlDb registry m a -> (a -> ExitCase b -> HasqlDb registry m c) -> (a -> HasqlDb registry m b) -> HasqlDb registry m (b, c)#

MonadThrow m => MonadThrow (HasqlDb registry m) Source #

Instance details

Defined in Arbiter.Hasql.HasqlDb

Methods

throwM :: (HasCallStack, Exception e) => e -> HasqlDb registry m a#

rethrowM :: Exception e => ExceptionWithContext e -> HasqlDb registry m a#

Applicative m => Applicative (HasqlDb registry m) Source #

Instance details

Defined in Arbiter.Hasql.HasqlDb

Methods

pure :: a -> HasqlDb registry m a#

(<*>) :: HasqlDb registry m (a -> b) -> HasqlDb registry m a -> HasqlDb registry m b#

liftA2 :: (a -> b -> c) -> HasqlDb registry m a -> HasqlDb registry m b -> HasqlDb registry m c#

(*>) :: HasqlDb registry m a -> HasqlDb registry m b -> HasqlDb registry m b#

(<*) :: HasqlDb registry m a -> HasqlDb registry m b -> HasqlDb registry m a#

Functor m => Functor (HasqlDb registry m) Source #

Instance details

Defined in Arbiter.Hasql.HasqlDb

Methods

fmap :: (a -> b) -> HasqlDb registry m a -> HasqlDb registry m b#

(<$) :: a -> HasqlDb registry m b -> HasqlDb registry m a#

Monad m => Monad (HasqlDb registry m) Source #

Instance details

Defined in Arbiter.Hasql.HasqlDb

Methods

(>>=) :: HasqlDb registry m a -> (a -> HasqlDb registry m b) -> HasqlDb registry m b#

(>>) :: HasqlDb registry m a -> HasqlDb registry m b -> HasqlDb registry m b#

return :: a -> HasqlDb registry m a#

MonadFail m => MonadFail (HasqlDb registry m) Source #

Instance details

Defined in Arbiter.Hasql.HasqlDb

Methods

fail :: HasCallStack => String -> HasqlDb registry m a#

MonadIO m => MonadIO (HasqlDb registry m) Source #

Instance details

Defined in Arbiter.Hasql.HasqlDb

Methods

liftIO :: IO a -> HasqlDb registry m a#

MonadUnliftIO m => MonadUnliftIO (HasqlDb registry m) Source #

Instance details

Defined in Arbiter.Hasql.HasqlDb

Methods

withRunInIO :: ((forall a. HasqlDb registry m a -> IO a) -> IO b) -> HasqlDb registry m b#

type RegistryOf (HasqlDb registry m) Source #

Instance details

Defined in Arbiter.Hasql.HasqlDb

type RegistryOf (HasqlDb registry m) = registry

type Handler (HasqlDb registry m) job result Source #

Instance details

Defined in Arbiter.Hasql.HasqlDb

type Handler (HasqlDb registry m) job result = Connection -> job -> HasqlDb registry m result

type HasqlEnv = Env Connection HasqlConfigSource #

The Env for HasqlDb.

data Db conn cfg (registry :: JobPayloadRegistry) (m :: Type -> Type) a#

A pooled backend's database monad.

Instances

Instances details

Monad m => HasPoolState conn (Db conn cfg registry m) #
Instance details Defined in Arbiter.Core.Backend Methods getPoolState :: Db conn cfg registry m (PoolState conn)# localPoolState :: (PoolState conn -> PoolState conn) -> Db conn cfg registry m a -> Db conn cfg registry m a#
Monad m => MonadReader (Env conn cfg registry) (Db conn cfg registry m) #
Instance details Defined in Arbiter.Core.Backend Methods ask :: Db conn cfg registry m (Env conn cfg registry)# local :: (Env conn cfg registry -> Env conn cfg registry) -> Db conn cfg registry m a -> Db conn cfg registry m a# reader :: (Env conn cfg registry -> a) -> Db conn cfg registry m a#
MonadCatch m => MonadCatch (Db conn cfg registry m) #
Instance details Defined in Arbiter.Core.Backend Methods catch :: (HasCallStack, Exception e) => Db conn cfg registry m a -> (e -> Db conn cfg registry m a) -> Db conn cfg registry m a# catchNoPropagate :: Exception e => Db conn cfg registry m a -> (ExceptionWithContext e -> Db conn cfg registry m a) -> Db conn cfg registry m a#
MonadMask m => MonadMask (Db conn cfg registry m) #
Instance details Defined in Arbiter.Core.Backend Methods mask :: HasCallStack => ((forall a. Db conn cfg registry m a -> Db conn cfg registry m a) -> Db conn cfg registry m b) -> Db conn cfg registry m b# uninterruptibleMask :: HasCallStack => ((forall a. Db conn cfg registry m a -> Db conn cfg registry m a) -> Db conn cfg registry m b) -> Db conn cfg registry m b# generalBracket :: HasCallStack => Db conn cfg registry m a -> (a -> ExitCase b -> Db conn cfg registry m c) -> (a -> Db conn cfg registry m b) -> Db conn cfg registry m (b, c)#
MonadThrow m => MonadThrow (Db conn cfg registry m) #
Instance details Defined in Arbiter.Core.Backend Methods throwM :: (HasCallStack, Exception e) => e -> Db conn cfg registry m a# rethrowM :: Exception e => ExceptionWithContext e -> Db conn cfg registry m a#
Applicative m => Applicative (Db conn cfg registry m) #
Instance details Defined in Arbiter.Core.Backend Methods pure :: a -> Db conn cfg registry m a# (<>) :: Db conn cfg registry m (a -> b) -> Db conn cfg registry m a -> Db conn cfg registry m b# liftA2 :: (a -> b -> c) -> Db conn cfg registry m a -> Db conn cfg registry m b -> Db conn cfg registry m c# (>) :: Db conn cfg registry m a -> Db conn cfg registry m b -> Db conn cfg registry m b# (<*) :: Db conn cfg registry m a -> Db conn cfg registry m b -> Db conn cfg registry m a#
Functor m => Functor (Db conn cfg registry m) #
Instance details Defined in Arbiter.Core.Backend Methods fmap :: (a -> b) -> Db conn cfg registry m a -> Db conn cfg registry m b# (<$) :: a -> Db conn cfg registry m b -> Db conn cfg registry m a#
Monad m => Monad (Db conn cfg registry m) #
Instance details Defined in Arbiter.Core.Backend Methods (>>=) :: Db conn cfg registry m a -> (a -> Db conn cfg registry m b) -> Db conn cfg registry m b# (>>) :: Db conn cfg registry m a -> Db conn cfg registry m b -> Db conn cfg registry m b# return :: a -> Db conn cfg registry m a#
MonadFail m => MonadFail (Db conn cfg registry m) #
Instance details Defined in Arbiter.Core.Backend Methods fail :: HasCallStack => String -> Db conn cfg registry m a#
MonadIO m => MonadIO (Db conn cfg registry m) #
Instance details Defined in Arbiter.Core.Backend Methods liftIO :: IO a -> Db conn cfg registry m a#
MonadUnliftIO m => MonadUnliftIO (Db conn cfg registry m) #
Instance details Defined in Arbiter.Core.Backend Methods withRunInIO :: ((forall a. Db conn cfg registry m a -> IO a) -> IO b) -> Db conn cfg registry m b#

data Env conn cfg (registry :: JobPayloadRegistry)#

Schema name, pool state, listener, and the driver's own state.

Constructors

Env
Fields schema :: SchemaName The schema the arbiter tables live in. poolState :: PoolState conn The pool and the pinned connection. listener :: Maybe Listener Resolved LISTEN source. `Nothing` runs poll-only. driverConfig :: cfg The driver's own state.

Instances

Instances details

Monad m => MonadReader (HasqlEnv registry) (HasqlDb registry m) Source #
Instance details Defined in Arbiter.Hasql.HasqlDb Methods ask :: HasqlDb registry m (HasqlEnv registry)# local :: (HasqlEnv registry -> HasqlEnv registry) -> HasqlDb registry m a -> HasqlDb registry m a# reader :: (HasqlEnv registry -> a) -> HasqlDb registry m a#
Monad m => MonadReader (Env conn cfg registry) (Db conn cfg registry m) #
Instance details Defined in Arbiter.Core.Backend Methods ask :: Db conn cfg registry m (Env conn cfg registry)# local :: (Env conn cfg registry -> Env conn cfg registry) -> Db conn cfg registry m a -> Db conn cfg registry m a# reader :: (Env conn cfg registry -> a) -> Db conn cfg registry m a#

newtype HasqlConfigSource #

Driver settings for HasqlDb.

Constructors

HasqlConfig
Fields preparedStatements :: Bool Prepare hot statements once per connection. Default: `True`.

Instances

Instances details

Monad m => MonadReader (HasqlEnv registry) (HasqlDb registry m) Source #
Instance details Defined in Arbiter.Hasql.HasqlDb Methods ask :: HasqlDb registry m (HasqlEnv registry)# local :: (HasqlEnv registry -> HasqlEnv registry) -> HasqlDb registry m a -> HasqlDb registry m a# reader :: (HasqlEnv registry -> a) -> HasqlDb registry m a#

data PoolState conn#

Pool and the pinned connection with its transaction depth.

Constructors

PoolState
Fields connectionPool :: Maybe (Pool conn) The pool to check connections out of. `Nothing` for a pinned-only env. pinned :: Maybe (conn, Int) The pinned connection and its transaction depth. Depth 0 means no open transaction.

class Monad m => HasPoolState conn (m :: Type -> Type) | m -> conn where#

Ambient access to the pool state.

Methods

getPoolState :: m (PoolState conn)#

The current pool state.

localPoolState :: (PoolState conn -> PoolState conn) -> m a -> m a#

Run an action under an adjusted pool state.

Instances

Instances details

Monad m => HasPoolState Connection (HasqlDb registry m) Source #
Instance details Defined in Arbiter.Hasql.HasqlDb Methods getPoolState :: HasqlDb registry m (PoolState Connection)# localPoolState :: (PoolState Connection -> PoolState Connection) -> HasqlDb registry m a -> HasqlDb registry m a#
Monad m => HasPoolState conn (Db conn cfg registry m) #
Instance details Defined in Arbiter.Core.Backend Methods getPoolState :: Db conn cfg registry m (PoolState conn)# localPoolState :: (PoolState conn -> PoolState conn) -> Db conn cfg registry m a -> Db conn cfg registry m a#

runHasqlDb :: forall (registry :: JobPayloadRegistry) m a. HasqlEnv registry -> HasqlDb registry m a -> m aSource #

Run a HasqlDb action in its env.

inTransaction :: forall (registry :: JobPayloadRegistry) m a. Connection -> SchemaName -> HasqlDb registry m a -> m aSource #

Arguments

:: forall (registry :: JobPayloadRegistry) m a. Connection	Connection with an open transaction
-> SchemaName
-> HasqlDb registry m a
-> m a

Run a HasqlDb action on one connection pinned as the caller's open transaction.

import Arbiter.Core qualified as Arb
import Arbiter.Hasql qualified as ArbH

_ <- Hasql.use conn (Session.script "BEGIN")
ArbH.inTransaction @MyRegistry conn "arbiter" $ do
  Arb.insertJob (Arb.defaultJob myPayload)
_ <- Hasql.use conn (Session.script "COMMIT")

inTransactionWith :: forall (registry :: JobPayloadRegistry) m a. HasqlConfig -> Connection -> SchemaName -> HasqlDb registry m a -> m aSource #

Arguments

:: forall (registry :: JobPayloadRegistry) m a. HasqlConfig	Driver settings
-> Connection	Connection with an open transaction
-> SchemaName
-> HasqlDb registry m a
-> m a

inTransaction with explicit settings, such as prepared statements off.

Environment creation

data HasqlConnectSource #

Connection settings for hasql 2: transport adapter (for example Pqi.Ffi.adapter) and connection string.

toHasqlConnect :: Adapter -> ByteString -> HasqlConnectSource #

Connection settings from a pqi adapter and a connection string. With the hasql2 flag off, the hasql 1.x shape takes only the connection string.

acquireConnect :: HasqlConnect -> IO (Either String Connection)Source #

Open a connection. A failure comes back as its description.

createHasqlEnv :: forall (registry :: JobPayloadRegistry) m. MonadIO m => Proxy registry -> HasqlConnect -> SchemaName -> m (HasqlEnv registry)Source #

Arguments

:: forall (registry :: JobPayloadRegistry) m. MonadIO m
=> Proxy registry	Type-level job payload registry
-> HasqlConnect	Connection settings
-> SchemaName
-> m (HasqlEnv registry)

Create a HasqlEnv with defaultPoolConfig. Size worker pools with createHasqlEnvWithConfig and Arbiter.Worker.poolConfigForWorkers. While anything listens, the listener holds one pool slot.

createHasqlEnvWithConfig :: forall (registry :: JobPayloadRegistry) m. MonadIO m => Proxy registry -> HasqlConnect -> SchemaName -> PoolConfig -> m (HasqlEnv registry)Source #

Arguments

:: forall (registry :: JobPayloadRegistry) m. MonadIO m
=> Proxy registry	Type-level job payload registry
-> HasqlConnect	Connection settings
-> SchemaName
-> PoolConfig	Pool configuration
-> m (HasqlEnv registry)

Create a HasqlEnv with custom pool settings. While anything listens, the listener holds one pool slot.

let config = PoolConfig
      { poolSize = 50
      , poolIdleTimeout = 120
      , poolStripes = Just 4
      }
env <- createHasqlEnvWithConfig (Proxy @MyRegistry) (toHasqlConnect Ffi.adapter connStr) "arbiter" config

createHasqlEnvWithPool :: forall (registry :: JobPayloadRegistry) m. MonadIO m => Proxy registry -> Pool Connection -> SchemaName -> m (HasqlEnv registry)Source #

Arguments

:: forall (registry :: JobPayloadRegistry) m. MonadIO m
=> Proxy registry	Type-level job payload registry
-> Pool Connection	Caller's connection pool
-> SchemaName
-> m (HasqlEnv registry)

Create a HasqlEnv over a caller's own connection pool. While anything listens, the listener holds one pool slot.

destroyHasqlEnv :: forall m (registry :: JobPayloadRegistry). MonadIO m => HasqlEnv registry -> m ()Source #

Close the idle connections in the env's pool. Connections in use stay open and go back to the pool. The pool stays usable.

disableListener :: forall conn cfg (registry :: JobPayloadRegistry). Env conn cfg registry -> Env conn cfg registry#

Turn off the shared LISTEN listener for an env, running poll-only.

useDedicatedListener :: forall m (registry :: JobPayloadRegistry). MonadIO m => HasqlConnect -> HasqlEnv registry -> m (HasqlEnv registry)Source #

Give the env a dedicated LISTEN connection that takes no pool slot.

setPreparedStatements :: forall (registry :: JobPayloadRegistry). Bool -> HasqlEnv registry -> HasqlEnv registrySource #

Enable or disable prepared statements on the hot path. On by default. Needs direct connections or a pooler that supports them.

Hasql settings

type HasqlSettings = SettingsSource #

hasql connection settings.

hasqlSettings :: ByteString -> HasqlSettingsSource #

Convert a connection string ByteString to hasql settings.

Exceptions

newtype HasqlConnectionErrorSource #

Thrown when a new hasql connection cannot be opened.

Constructors

HasqlConnectionError String

Instances

Instances details

Exception HasqlConnectionError Source #
Instance details Defined in Arbiter.Hasql.HasqlDb Methods toException :: HasqlConnectionError -> SomeException# fromException :: SomeException -> Maybe HasqlConnectionError# displayException :: HasqlConnectionError -> String# backtraceDesired :: HasqlConnectionError -> Bool#
Show HasqlConnectionError Source #
Instance details Defined in Arbiter.Hasql.HasqlDb Methods showsPrec :: Int -> HasqlConnectionError -> ShowS# show :: HasqlConnectionError -> String# showList :: [HasqlConnectionError] -> ShowS#