Module pool (3.27.0)

Pools managing shared Session objects.

Classes

AbstractSessionPool

AbstractSessionPool(labels=None, database_role=None)

Specifies required API for concrete session pool implementations.

Parameters

Name	Description
`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

Name	Description
`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

Name	Description
`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

Name	Description
`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

Name	Description
`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

Name	Description
`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.