Module pool (3.35.0)

Pools managing shared Session objects.

Classes

AbstractSessionPool

AbstractSessionPool(labels=None, database_role=None)

Specifies required API for concrete session pool implementations.

Parameters
NameDescription
labels dict (str -> str) or None

(Optional) user-assigned labels for sessions created by the pool.

database_role str

(Optional) user-assigned database_role for the session.

BurstyPool

BurstyPool(target_size=10, labels=None, database_role=None)

Concrete session pool implementation:

  • "Pings" existing sessions via session.exists before returning them.

  • Creates a new session, rather than blocking, when get is called on an empty pool.

  • Discards the returned session, rather than blocking, when put is called on a full pool.

Parameters
NameDescription
target_size int

max pool size

labels dict (str -> str) or None

(Optional) user-assigned labels for sessions created by the pool.

database_role str

(Optional) user-assigned database_role for the session.

FixedSizePool

FixedSizePool(size=10, default_timeout=10, labels=None, database_role=None)

Concrete session pool implementation:

  • Pre-allocates / creates a fixed number of sessions.

  • "Pings" existing sessions via session.exists before returning them, and replaces expired sessions.

  • Blocks, with a timeout, when get is called on an empty pool. Raises after timing out.

  • Raises when put is called on a full pool. That error is never expected in normal practice, as users should be calling get followed by put whenever in need of a session.

Parameters
NameDescription
size int

fixed pool size

default_timeout int

default timeout, in seconds, to wait for a returned session.

labels dict (str -> str) or None

(Optional) user-assigned labels for sessions created by the pool.

database_role str

(Optional) user-assigned database_role for the session.

PingingPool

PingingPool(
    size=10, default_timeout=10, ping_interval=3000, labels=None, database_role=None
)

Concrete session pool implementation:

  • Pre-allocates / creates a fixed number of sessions.

  • Sessions are used in "round-robin" order (LRU first).

  • "Pings" existing sessions in the background after a specified interval via an API call (session.ping()).

  • Blocks, with a timeout, when get is called on an empty pool. Raises after timing out.

  • Raises when put is called on a full pool. That error is never expected in normal practice, as users should be calling get followed by put whenever in need of a session.

The application is responsible for calling ping at appropriate times, e.g. from a background thread.

Parameters
NameDescription
size int

fixed pool size

default_timeout int

default timeout, in seconds, to wait for a returned session.

ping_interval int

interval at which to ping sessions.

labels dict (str -> str) or None

(Optional) user-assigned labels for sessions created by the pool.

database_role str

(Optional) user-assigned database_role for the session.

SessionCheckout

SessionCheckout(pool, **kwargs)

Context manager: hold session checked out from a pool.

Parameter
NameDescription
pool concrete subclass of AbstractSessionPool

Pool from which to check out a session.

TransactionPingingPool

TransactionPingingPool(
    size=10, default_timeout=10, ping_interval=3000, labels=None, database_role=None
)

Concrete session pool implementation:

Deprecated: TransactionPingingPool no longer begins a transaction for each of its sessions at startup. Hence the TransactionPingingPool is same as PingingPool and maybe removed in the future.

In addition to the features of PingingPool, this class creates and begins a transaction for each of its sessions at startup.

When a session is returned to the pool, if its transaction has been committed or rolled back, the pool creates a new transaction for the session and pushes the transaction onto a separate queue of "transactions to begin." The application is responsible for flushing this queue as appropriate via the pool's begin_pending_transactions method.

Parameters
NameDescription
size int

fixed pool size

default_timeout int

default timeout, in seconds, to wait for a returned session.

ping_interval int

interval at which to ping sessions.

labels dict (str -> str) or None

(Optional) user-assigned labels for sessions created by the pool.

database_role str

(Optional) user-assigned database_role for the session.