db_pool

Types

Message

opaque </>

pub opaque type Message(conn, err)

Pool

opaque </>

A Pool configuration. Holds the size of the pool and functions for opening and closing connections.

pub opaque type Pool(conn, err)

PoolError

</>

Errors that can occur when interacting with the pool.

ConnectionError(err) wraps an error returned by the on_open or on_close callback.
ConnectionTimeout is returned when a checkout request times out while waiting in the queue.
ConnectionUnavailable is returned when the CoDel algorithm drops a request due to sustained overload, or when the pool shuts down while callers are waiting.

pub type PoolError(err) {
  ConnectionError(err)
  ConnectionTimeout
  ConnectionUnavailable
}

Constructors

```
ConnectionError(err)
```
```
ConnectionTimeout
```
```
ConnectionUnavailable
```

Values

Expects the conn value to be the same connection that was originally checked out, and caller should be the Pid that checked it out. If the caller has no active connection the checkin is silently ignored.

checkout

</>

pub fn checkout(
  pool: process.Subject(Message(conn, err)),
  caller: process.Pid,
  timeout: Int,
  deadline: Int,
) -> Result(conn, PoolError(err))

Checks out a connection from the pool.

The caller should be process.self() of the calling process. The pool monitors this process and reclaims the connection if it crashes.

If a connection is available it is returned immediately. If all connections are in use the caller is added to a FIFO queue and will receive a connection when one becomes available, or a ConnectionTimeout error after timeout milliseconds.

The deadline parameter sets the maximum time in milliseconds that the connection may be held. If the caller has not checked in by then, the pool forcibly closes the connection, replaces it, and the caller is left holding a now-closed connection.

Re-entrant: calling checkout again from the same process returns the already checked-out connection. The original deadline is preserved — a second checkout cannot extend it.

Panics if the pool actor is unreachable.

new

</>

pub fn new() -> Pool(conn, err)

Returns a Pool that needs to be configured.

on_active

</>

pub fn on_active(
  pool: Pool(conn, err),
  handle_active: fn(conn) -> Nil,
) -> Pool(conn, err)

Sets the Pool’s on_active function. The provided function will be called on connections as they’re removed from the pool’s list of idle connections and become active.

on_close

</>

pub fn on_close(
  pool: Pool(conn, err),
  handle_close: fn(conn) -> Result(Nil, err),
) -> Pool(conn, err)

Sets the Pool’s on_close function. The provided function will be called on each connection when the pool is shut down or exits.

on_idle

</>

pub fn on_idle(
  pool: Pool(conn, err),
  handle_idle: fn(conn) -> Nil,
) -> Pool(conn, err)

Sets the Pool’s on_idle function. The provided function will be called on connections when they’re checked back in to the pool. If the connection is immediately passed to a waiting caller, the callback will not be called. The callback is also called on every connection at startup.

on_open

</>

pub fn on_open(
  pool: Pool(conn, err),
  handle_open: fn() -> Result(conn, err),
) -> Pool(conn, err)

Sets the Pool’s on_open function. The provided function will be called at startup to create connections.

queue_interval

</>

pub fn queue_interval(
  pool: Pool(conn, err),
  interval: Int,
) -> Pool(conn, err)

Sets the CoDel queue interval in milliseconds. This is the length of each CoDel measurement interval. The pool evaluates queue health at each interval boundary. Defaults to 1000ms.

queue_target

</>

pub fn queue_target(
  pool: Pool(conn, err),
  target: Int,
) -> Pool(conn, err)

Sets the CoDel queue target in milliseconds. This is the maximum acceptable queue delay before the pool considers itself overloaded. Defaults to 50ms.

shutdown

</>

pub fn shutdown(
  pool: process.Subject(Message(conn, err)),
  timeout: Int,
) -> Result(Nil, PoolError(err))

Shuts down the pool gracefully within timeout milliseconds.

All waiting callers in the queue are drained and sent a ConnectionUnavailable error. Active (checked-out) connections are closed, their deadline timers cancelled, and their monitors removed. Idle connections are then closed via the configured on_close callback.

Panics if the pool actor is unreachable or does not respond within the timeout.

size

</>

pub fn size(pool: Pool(conn, err), size: Int) -> Pool(conn, err)

Sets the size of the pool. At startup the pool will create size number of connections.

start

</>

pub fn start(
  pool: Pool(conn, err),
  name: process.Name(Message(conn, err)),
  timeout: Int,
) -> Result(
  actor.Started(process.Subject(Message(conn, err))),
  actor.StartError,
)

Starts a connection pool and registers it under name. All configured connections are opened eagerly during initialisation.

The timeout parameter is the maximum time in milliseconds allowed for the actor to initialise (open all connections).

The pool actor traps exits so it can perform cleanup when its parent or linked processes terminate.

supervised

</>

pub fn supervised(
  pool: Pool(conn, err),
  name: process.Name(Message(conn, err)),
  timeout: Int,
) -> supervision.ChildSpecification(
  process.Subject(Message(conn, err)),
)

Creates a supervision.ChildSpecification so the pool can be added to an application’s supervision tree.

The timeout parameter is used for both the actor initialisation timeout and the supervisor’s shutdown timeout. The restart strategy is set to Transient — the pool is restarted only if it terminates abnormally.

with_connection

</>

pub fn with_connection(
  pool: process.Subject(Message(conn, err)),
  timeout: Int,
  deadline: Int,
  next: fn(conn) -> t,
) -> Result(t, PoolError(err))

Checks out a connection from the pool and passes it to the provided callback function. The connection is automatically checked back in after the callback function returns.

If the callback panics, the connection is not checked in immediately. It is reclaimed when the caller process exits (via the pool’s monitor).

Panics if the pool actor is unreachable (crashed or shut down).