Skip to content

Connection options and timeouts ​

Layered connection options and the client-side time limit of adorm operations, in adorm.executor.options. connection_options and timeout are also importable from adorm, Timeout from adorm.executor. See the connection options topic.

python
import adorm
from adorm.executor import Timeout
from adorm.executor.options import (
    ADORM_OPTIONS,
    block_options,
    check_hook_options,
    check_options,
    MAX_TIMEOUT_OPTION,
    resolve_options,
    ResolvedOptions,
    ROLE_OPTION,
    session_options,
    set_session_options,
    TIMEOUT_OPTIONS,
)

Options ​

OptionKindValueApplied by
acquire_timeoutadormseconds a slot acquisition waits, positive and finitethe router, when a session acquires a slot; a transaction, when it waits for a savepoint of another task
commit_timeoutadormseconds a slot inside a transaction waits for the next request, positive and finite, or None for no limitthe slot of a transaction, with the value in effect when the transaction acquired it
statement_timeoutdatabaseseconds from 0 (no limit) to MAX_TIMEOUT_OPTION, or None for the database's defaultthe database, through the driver
lock_timeoutdatabaseas statement_timeoutthe database, through the driver
idle_in_transaction_session_timeoutdatabaseas statement_timeoutthe database, through the driver
roledatabasea role name, a non-empty string, or None for the database's defaultthe database, through the driver (PostgreSQL's SET ROLE)
a custom option, such as app.user_iddatabasea string, or None for the database's defaultthe database, through a driver that declares custom options
any other namedatabasewhat the driver accepts, or None for the database's defaultthe database, through the driver

A custom option's name is two or more lowercase ASCII identifiers joined by dots (is_custom_option()): PostgreSQL's customized options, which row-level security policies read with current_setting(). It is not a Python identifier, so it is passed by unpacking a mapping:

python
with adorm.connection_options(**{"app.user_id": "42"}):
    await Note.objects.count()

Layers, from first to last; a later layer overrides an earlier one:

  1. the profile: its pool settings for the adorm options; for the database options the options the driver sets on every new connection (Driver.connection_defaults()), overridden by its options;
  2. the options the profile's on_acquire hook returns for the slot's lease (check_hook_options());
  3. the session (Session.set_options());
  4. the enclosing connection_options() blocks, innermost last.

When a layer's option ends, the slot sets the value of the layer below it, the database's default only when no layer below sets the option.

A database option is sent only to a driver that declares it in Capabilities.connection_options. An operation with an undeclared option raises NotSupportedError before it takes a slot. An option whose value is None is not sent and needs no declaration. The Django driver on PostgreSQL and the native PostgreSQL driver declare statement_timeout, lock_timeout, idle_in_transaction_session_timeout, role and custom options; the Django driver on other databases declares none (databases).

adorm.connection_options(**options) ​

A synchronous context manager (with, not async with) that sets connection options for its block in a context variable. Its options override those of the same names in enclosing blocks, the session and the profile. On exit, also on an exception, the previous block layer is restored. Tasks created inside the block inherit its options, also when they outlive it. as binds the block layer in effect inside the block, a read-only mapping. Values are checked as in check_options(); a refused value raises ValueError and sets nothing.

python
with adorm.connection_options(statement_timeout=5, lock_timeout=2):
    await Member.objects.filter(active=False).delete()

with adorm.connection_options(acquire_timeout=1):
    count = await Member.objects.count()          # SessionTimeout after 1 s without a slot

with adorm.connection_options(statement_timeout=60) as layer:
    with adorm.connection_options(statement_timeout=None):
        ...                                       # the database's default

Outside a transaction the slot sets database options with SET and resets with RESET those a later operation does not run with. Inside a transaction it uses SET LOCAL. It sends nothing when the connection already has the values (see Slot).

adorm.timeout(delay) ​

A Timeout block of delay seconds; None sets no limit. A delay that is neither a number nor None, or is NaN, raises ValueError.

python
try:
    async with adorm.timeout(5):
        members = [m async for m in Member.objects.filter(active=True)]
except adorm.OperationTimeout as exc:
    if exc.phase == "waiting_for_slot":
        ...                                  # the pool is saturated
    else:
        log.warning("slow query on %r: %r", exc.session, exc.operation)

adorm.executor.Timeout ​

A time limit for the adorm operations of an async with block, wrapping asyncio.timeout(). On expiry the task running the block is cancelled and the block raises OperationTimeout from the TimeoutError. Other exceptions, including a TimeoutError the block raises itself, pass through unchanged.

The operations of the block report their state to it, including those of tasks that inherit its context (asyncio.create_task(), TaskGroup, gather()):

OperationTimeout attributeValue
phase"waiting_for_slot" while the operation waits for a slot (or for a savepoint of another task in its transaction), "executing" once its request is sent
operationthe adorm operation; for a transaction's own requests their name: "begin", "commit", "rollback", "savepoint", "release_savepoint", "rollback_to_savepoint"
sessionthe operation's session
timeoutdelay

The reported operation is the first one the expiry's cancellation reached, else the oldest one in progress (as for a task not awaited inside the block). With neither, phase, operation and session are None. cancellation_outcome() of the error reports what the interrupted operation did, also in a child task; for an operation in progress it reports what the block's CancelledError reports. Nested blocks each see the operations inside them; the block that expired raises.

MethodMeaning
when()the deadline in the event loop's time; None for no limit or before the block is entered
reschedule(when)moves the deadline to when (the loop's time, None for no limit); RuntimeError before the block is entered
expired()whether the deadline passed and cancelled the block

A block is entered once; entering it again raises RuntimeError.

python
async with adorm.timeout(10) as t:
    await prepare()
    t.reschedule(asyncio.get_running_loop().time() + 2)   # two more seconds from now
    await Member.objects.filter(pk=1).update(active=False)

Layers and resolution ​

adorm.executor.options.check_options(options) ​

Returns the mapping options, checked, as a read-only mapping. Raises TypeError for anything but a mapping and ValueError for:

  • a name that is neither an identifier nor a custom option name;
  • an acquire_timeout that is not a positive, finite number of seconds;
  • a commit_timeout that is neither that nor None;
  • a value of a TIMEOUT_OPTIONS option that is neither a number of seconds from 0 to MAX_TIMEOUT_OPTION nor None;
  • a role that is neither a non-empty string without NUL nor None;
  • a custom option whose value is neither a string without NUL nor None.

Other values are checked by the driver that sets them.

python
check_options({"statement_timeout": 5, "work_mem": "64MB"})   # mappingproxy({...})
check_options({"lock_timeout": -1})                           # ValueError
check_options({"role": "alice", "app.user_id": "42"})          # mappingproxy({...})
check_options({"app.user_id": 42})                             # ValueError: a string

adorm.executor.options.check_hook_options(result, hook, profile_name) ​

The database options a profile hook returned, checked as in check_options(): an empty mapping for None, the checked mapping for a mapping. Raises TypeError for another value and ValueError for acquire_timeout or commit_timeout and as check_options(). hook and profile_name name the hook in the message.

python
check_hook_options({"role": "alice"}, "on_acquire", "default")    # mappingproxy({'role': 'alice'})
check_hook_options("alice", "on_acquire", "default")              # TypeError

adorm.executor.options.block_options() ​

The options of the enclosing connection_options() blocks of the current context, a read-only mapping.

adorm.executor.options.session_options(session) ​

The options set on session, the same as Session.options.

adorm.executor.options.set_session_options(session, options) ​

Replaces the options of session with the mapping options, checked; an empty mapping removes them. Returns the checked options. Thread-safe.

adorm.executor.options.resolve_options(session, pool) ​

The ResolvedOptions in effect in the current context for session on pool: the pool's acquire_timeout, commit_timeout and options, overridden by the session's options, then by those of the enclosing blocks.

python
with adorm.connection_options(statement_timeout=5):
    resolve_options(session, pool)
# ResolvedOptions(acquire_timeout=30.0, commit_timeout=60.0, database=mappingproxy({'statement_timeout': 5}),
#                 profile=mappingproxy({}), overrides=mappingproxy({'statement_timeout': 5}))

adorm.executor.options.ResolvedOptions ​

A frozen dataclass of the options in effect.

FieldMeaning
acquire_timeoutseconds an acquisition waits
commit_timeoutseconds the slot of a transaction waits for its next request, None for no limit
databasethe database options to set, without those whose value is None
profilethe profile's layer of database options (Pool.options)
overridesthe session's and the blocks' database options, None values included

for_lease(lease) returns the database options to set on lease's slot: database with the lease's hook_options placed between profile and overrides, without the options whose value is None.

adorm.executor.options.ADORM_OPTIONS ​

frozenset({"acquire_timeout", "commit_timeout"}): the options adorm applies itself; they never reach a driver.

adorm.executor.options.TIMEOUT_OPTIONS ​

frozenset({"statement_timeout", "lock_timeout", "idle_in_transaction_session_timeout"}): the database options whose value check_options() checks as a number of seconds.

adorm.executor.options.ROLE_OPTION ​

"role": the database option naming the role the connection acts as.

adorm.executor.options.MAX_TIMEOUT_OPTION ​

2147483.647: the largest value of a TIMEOUT_OPTIONS option in seconds (PostgreSQL's limit of 2147483647 ms).

Released under the MIT License.