Safe Haskell	None
Language	GHC2021

Database.Bolty.Pool

Description

Connection pooling with health-check validation and retry configuration.

Synopsis

data BoltPool = BoltPool {
- bpPool :: !(Pool Connection)
- bpMaxRetries :: !Int
- bpRetryConfig :: !RetryConfig
- bpValidation :: !ValidationStrategy
- bpActiveConns :: !(IORef Int)
- bpTotalAcqs :: !(IORef Int)
- bpTotalWaitNs :: !(IORef Word64)
}
data PoolConfig = PoolConfig {
- maxConnections :: Int
- idleTimeout :: Double
- maxPingRetries :: Int
- retryConfig :: RetryConfig
- validationStrategy :: ValidationStrategy
}
defaultPoolConfig :: PoolConfig
data ValidationStrategy
- = AlwaysPing
- | PingIfIdle !Int
- | NeverPing
data RetryConfig = RetryConfig {
- maxRetries :: !Int
- initialDelay :: !Int
- maxDelay :: !Int
}
defaultRetryConfig :: RetryConfig
data PoolCounters = PoolCounters {
- pcActive :: !Int
- pcTotalAcqs :: !Int
- pcTotalWaitNs :: !Word64
}
createPool :: HasCallStack => ValidatedConfig -> PoolConfig -> IO BoltPool
destroyPool :: BoltPool -> IO ()
withConnection :: HasCallStack => BoltPool -> (Connection -> IO a) -> IO a
data CheckedOutConnection = CheckedOutConnection {
- cocConnection :: !Connection
- cocLocalPool :: !(LocalPool Connection)
- cocBoltPool :: !BoltPool
}
acquireConnection :: BoltPool -> IO CheckedOutConnection
releaseConnection :: CheckedOutConnection -> IO ()
releaseConnectionOnError :: CheckedOutConnection -> IO ()
poolCounters :: BoltPool -> IO PoolCounters

Documentation

data BoltPool Source #

A pool of Neo4j connections with health-check and retry configuration.

Constructors

BoltPool
Fields bpPool :: !(Pool Connection) bpMaxRetries :: !Int bpRetryConfig :: !RetryConfig bpValidation :: !ValidationStrategy bpActiveConns :: !(IORef Int) bpTotalAcqs :: !(IORef Int) bpTotalWaitNs :: !(IORef Word64)

data PoolConfig Source #

Configuration for the connection pool.

Constructors

PoolConfig

Fields

maxConnections :: Int
Maximum number of open connections. Default: 10.
idleTimeout :: Double
Seconds before an idle connection is closed. Default: 60.
maxPingRetries :: Int
Number of additional attempts after a ping failure. Default: 1. Total attempts = 1 + maxPingRetries.
retryConfig :: RetryConfig
Retry configuration for transient failures. Default: defaultRetryConfig.
validationStrategy :: ValidationStrategy
How to validate connections on checkout. Default: AlwaysPing.

defaultPoolConfig :: PoolConfig Source #

Default pool configuration: 10 max connections, 60 second idle timeout, 1 ping retry.

data ValidationStrategy Source #

Strategy for validating connections when they are checked out of the pool.

Constructors

AlwaysPing	Always send RESET before use (current default, safest).
PingIfIdle !Int	Only ping if the connection has been idle for more than N seconds. Connections used within the last N seconds are assumed healthy.
NeverPing	Skip health check entirely (fastest, use only in trusted environments).

Instances

Instances details

Show ValidationStrategy Source #
Instance details Defined in Database.Bolty.Pool Methods showsPrec :: Int -> ValidationStrategy -> ShowS # show :: ValidationStrategy -> String # showList :: [ValidationStrategy] -> ShowS #
Eq ValidationStrategy Source #
Instance details Defined in Database.Bolty.Pool Methods (==) :: ValidationStrategy -> ValidationStrategy -> Bool # (/=) :: ValidationStrategy -> ValidationStrategy -> Bool #

data RetryConfig Source #

Configuration for retry logic on transient failures.

Constructors

RetryConfig
Fields maxRetries :: !Int Maximum number of retry attempts. Default: 5. initialDelay :: !Int Initial delay in microseconds before first retry. Default: 200000 (200ms). maxDelay :: !Int Maximum delay in microseconds between retries. Default: 5000000 (5s).

Instances

Instances details

Show RetryConfig Source #
Instance details Defined in Database.Bolty.Pool Methods showsPrec :: Int -> RetryConfig -> ShowS # show :: RetryConfig -> String # showList :: [RetryConfig] -> ShowS #
Eq RetryConfig Source #
Instance details Defined in Database.Bolty.Pool Methods (==) :: RetryConfig -> RetryConfig -> Bool # (/=) :: RetryConfig -> RetryConfig -> Bool #

defaultRetryConfig :: RetryConfig Source #

Default retry configuration: 5 retries, 200ms initial delay, 5s max delay.

data PoolCounters Source #

Snapshot of pool-level counters.

Constructors

PoolCounters
Fields pcActive :: !Int Number of connections currently checked out. pcTotalAcqs :: !Int Lifetime count of connection acquisitions. pcTotalWaitNs :: !Word64 Cumulative nanoseconds spent waiting for connections.

Instances

Instances details

Show PoolCounters Source #
Instance details Defined in Database.Bolty.Pool Methods showsPrec :: Int -> PoolCounters -> ShowS # show :: PoolCounters -> String # showList :: [PoolCounters] -> ShowS #
Eq PoolCounters Source #
Instance details Defined in Database.Bolty.Pool Methods (==) :: PoolCounters -> PoolCounters -> Bool # (/=) :: PoolCounters -> PoolCounters -> Bool #

createPool :: HasCallStack => ValidatedConfig -> PoolConfig -> IO BoltPool Source #

Create a new connection pool. If the server advertises connection.recv_timeout_seconds, the pool's idle timeout is capped to min(configured, hint - 5) so connections are recycled before the server closes them.

destroyPool :: BoltPool -> IO () Source #

Destroy the pool, closing all connections.

withConnection :: HasCallStack => BoltPool -> (Connection -> IO a) -> IO a Source #

Acquire a healthy connection from the pool, run an action, then release it. Validates the connection using the configured ValidationStrategy. On connection failure during the action, discards the dead connection and retries once with a fresh one.

data CheckedOutConnection Source #

A checked-out connection handle, bundling the connection with its local pool reference for proper release.

Constructors

CheckedOutConnection
Fields cocConnection :: !Connection cocLocalPool :: !(LocalPool Connection) cocBoltPool :: !BoltPool

acquireConnection :: BoltPool -> IO CheckedOutConnection Source #

Acquire a validated connection from the pool. The caller is responsible for releasing it with releaseConnection or releaseConnectionOnError.

This is the low-level primitive behind withConnection. Prefer withConnection for simple request-response patterns. Use acquireConnection when you need the connection to outlive a callback (e.g. for streaming with bracketIO).

releaseConnection :: CheckedOutConnection -> IO () Source #

Release a connection back to the pool after successful use.

releaseConnectionOnError :: CheckedOutConnection -> IO () Source #

Release a connection after an error, destroying it instead of returning it to the pool (since it may be in a bad state).

poolCounters :: BoltPool -> IO PoolCounters Source #

Read a snapshot of the pool's lifetime counters.