GitHub

PgPoolService

API reference for PgPoolService.

A pool of sessions.

  • get: a session until the scope closes
  • reserve: a pinned session until the scope closes (transactions and listeners)
  • use(f): a session for as long as f's effect runs
  • invalidate(connection): replace a session
  • stats: a snapshot of session occupancy (sessions, not statements; a session that has just failed can show as idle until the pool removes it)

Attributes

AttributeTypeDescription
config= config
getEffect[PgConnection, SqlError, Scope]

Checks out a session until the current scope closes, replacing one past its connection_ttl. Fails with an SqlError when no session can be connected or acquire_timeout passes first.

reserveEffect[PgConnection, SqlError, Scope]

get, pinned: the session is reserved for the connection given until the current scope closes (for transactions and listeners). Fails as get does.

statsEffect[PoolStats]

A snapshot of session occupancy; never fails. It counts sessions, not statements, and a session that has just failed can show as idle until the pool removes it.

Functions

__init__

__init__(config, pool, check_out, slow_use, hand_out) -> None
ParameterTypeDescription
configPgPoolConfig
poolPool[PgConnection, SqlError]
check_outEffect[PgConnection, SqlError, Scope]
slow_useCallable[[], bool]
hand_outCallable[[PgConnection], Effect[PgConnection]]
def __init__(
    self,
    config: PgPoolConfig,
    pool: Pool[PgConnection, SqlError],
    check_out: Effect[PgConnection, SqlError, Scope],
    slow_use: Callable[[], bool],
    hand_out: Callable[[PgConnection], Effect[PgConnection]],
) -> None:
    self.config = config
    self._pool = pool
    self._check_out = check_out
    self._slow_use = slow_use
    self._hand_out = hand_out

use

use[A, E, R](f) -> Effect[A, E | SqlError, R]

Lends a session to f for as long as its effect runs and takes it back on any exit, without opening a scope; a lease that must outlive the effect (a stream, a transaction) takes get or reserve. Fails with f's errors, or an SqlError as get does.

ParameterTypeDescription
fCallable[[PgConnection], Effect[A, E, R]]

Returns Effect[A, E | SqlError, R]

def use[A, E, R](
    self, f: Callable[[PgConnection], Effect[A, E, R]]
) -> Effect[A, E | SqlError, R]:
    """Lends a session to ``f`` for as long as its effect runs and
    takes it back on any exit, without opening a scope; a lease that
    must outlive the effect (a stream, a transaction) takes ``get`` or
    ``reserve``. Fails with ``f``'s errors, or an ``SqlError`` as
    ``get`` does."""

    def body() -> Effect[A, E | SqlError, R]:
        if self._slow_use():
            return scoped(self._check_out.flat_map(f))
        return self._pool.use(lambda connection: self._hand_out(connection).flat_map(f))

    return _Suspend(body)

invalidate

invalidate(connection) -> Effect[None]

Removes connection's session so the pool can replace it; never fails. Fatal protocol and socket errors invalidate sessions on their own.

ParameterTypeDescription
connectionPgConnection

Returns Effect[None]

def invalidate(self, connection: PgConnection) -> Effect[None]:
    """Removes ``connection``'s session so the pool can replace it;
    never fails. Fatal protocol and socket errors invalidate sessions
    on their own."""
    return self._pool.invalidate(connection.base)