Skip to content

Events ​

A slot answers the client with events. Every request it runs ends with one outcome event; a commit or rollback adds a callback event; the driver connection adds callbacks and events the database raised on its own. On the client, the event channel of each slot lease interprets each event: it returns a result to the code that awaits it, runs a callback, or calls the functions subscribed to it.

text
client                        slot                             DriverConnection
  ── Request ──▶ request queue ──▶ runs requests in order ───▶ execute(), commit() …
                                     │                               │
  ◀── EventChannel ◀── event queue ◀─┤ one outcome per request       │
                                     │ ON_COMMIT, ON_ROLLBACK        │
                                     └ emitted events ◀───────────── emit(CallbackEvent | BackendEvent)

EventChannel
  ├── outcome of an awaited request ──▶ the awaiting call returns, raises or ends cancelled
  ├── callback with handlers ─────────▶ the handlers run (on_commit callbacks of a transaction)
  └── anything else ──────────────────▶ lease.events; the pool's EventBus once the lease ends

The events ​

EventDelivered byWhen
ResultEvent(request_id, value)the slota request returned: rows, a scalar, a count
ErrorEvent(request_id, error)the slota request raised an adorm exception
CancelledEvent(request_id, started)the slota request was cancelled at the client's request
CallbackEvent("on_commit")the slota commit request succeeded, before its outcome
CallbackEvent("on_rollback")the slota rollback request succeeded, before its outcome; the slot rolled back an abandoned transaction
CallbackEvent(name, payload)the driver connectiona point in the connection's life the client runs callbacks for
BackendEvent(name, channel, payload)the driver connectionthe database or the target raised something on its own, such as PostgreSQL NOTIFY

Exactly one of ResultEvent, ErrorEvent and CancelledEvent ends each request the slot accepted. Results and errors arrive in the order of the requests; the CancelledEvent of a request that was still queued arrives as soon as it is cancelled, ahead of the outcomes of earlier requests. An event a connection emits while a request runs arrives before that request's outcome.

Signals of the target (Django's post_save, SQLAlchemy's ORM events) and the target's own on_commit hooks run on the driver side and do not reach the client. A driver reports an effect the client must know about as a CallbackEvent or a BackendEvent. Outcome events and the names on_commit and on_rollback are delivered only by the slot; when a connection emits them, the slot drops and logs them.

How adorm interprets an event ​

Return a result. lease.call() and every operation that a session or a transaction runs await their request's outcome on the channel: a ResultEvent returns the value, an ErrorEvent raises the error, a CancelledEvent ends the call cancelled. A CancelledEvent for a call whose task was not cancelled raises InterfaceError. Code that writes to the request queue directly reads the outcomes from lease.events.

python
async with await router.acquire(session) as lease:
    rows = await lease.call("execute", operation)                 # ResultEvent → return value

    lease.requests.put_nowait(request := Request("execute", (operation,)))
    match await lease.events.get():
        case ResultEvent(request_id, value): ...
        case ErrorEvent(request_id, error): ...
        case CancelledEvent(request_id, started): ...

Run a callback. A handler registered on the channel with on(name, handler) runs for every CallbackEvent of that name; the event is not queued. An atomic() block registers one for on_commit and runs its on_commit callbacks when the slot reports the commit.

python
async with adorm.atomic() as tx:
    await Member.objects.create(name="Ana")
    tx.on_commit(lambda: mailer.send_welcome("Ana"))     # runs when CallbackEvent("on_commit") arrives

async with await router.acquire(session) as lease:
    lease.channel.on("cache_cleared", lambda event: cache.drop(event.payload["keys"]))

Call another function. Each pool has an EventBus as events. It receives the callbacks and backend events nobody claimed: those a connection emits while its slot is idle, and those still unread on lease.events when the lease is released. Subscribe by type, name and channel:

python
pool = await router.get_pool("default")
unsubscribe = pool.events.subscribe(
    BackendEvent, lambda event: orders.refresh(event.payload), name="notify", channel="orders"
)

Backend events ​

A driver connection reports what the database does on its own as a BackendEvent. The Django driver (on PostgreSQL with psycopg 3) and the native PostgreSQL driver emit:

EventWhenWhere it goes
BackendEvent("notice", severity, payload)the server sends a notice or warning with a statement's result: RAISE NOTICE in a trigger or function, a WARNINGthe lease's channel, before the request's outcome; unread, to the pool's EventBus when the lease ends
BackendEvent("notify", channel, payload)a notification arrives on a channel the connection listens onan adorm.listen() block
BackendEvent("connection_lost", None, reason)the database connection ended without adorm closing it; the Django driver notices it only while the connection listens, the native driver at any timethe lease's channel, or the pool's EventBus while the slot is idle

The notices of a session's operations reach the subscribers of the pool's EventBus when the slot is released (inside a transaction, when the transaction ends), in the order the server sent them. Subscribe by name, and by severity as the channel:

python
pool = await adorm.settings.default_router().get_pool("default")
pool.events.subscribe(BackendEvent, lambda e: log.info("%s", e.payload["message"]), name="notice")
pool.events.subscribe(BackendEvent, alert, name="notice", channel="WARNING")

await Club.objects.filter(slug="koper-sailing").update(city="Koper")
# the trigger's RAISE WARNING 'check the clubs' → alert(BackendEvent("notice", "WARNING", {"message": "check the clubs", ...}))

Code that holds a lease reads the notices of its own requests from lease.events, queued before the request's outcome returns.

python
async with router.slot(session) as lease:
    await lease.call("execute", update)
    notices = [lease.events.get_nowait() for _ in range(lease.events.qsize())]

Listening for notifications ​

adorm.listen() holds a slot whose connection listens on PostgreSQL channels and returns each notification as a BackendEvent("notify", channel, payload). Channel names are used exactly as given (quoted in LISTEN), so "Orders" and "orders" differ; on the PostgreSQL drivers a name is at most 63 bytes.

python
async with adorm.listen("orders", "invoices") as listener:
    async for event in listener:
        match event.channel:
            case "orders":
                await refresh_order(int(event.payload))
            case "invoices":
                await listener.unlisten("invoices")
sql
-- any session of the database, e.g. a trigger
SELECT pg_notify('orders', '42');
  • The slot counts against the pool's max_connections while the block runs, and the block's flow holds it: an operation of the same flow that needs a slot of a full pool raises DeadlockError. Run the block's other work in another task or on another pool.
  • PostgreSQL delivers a notification sent inside a transaction when that transaction commits, never after a rollback; notifications of one sending transaction arrive in the order they were sent.
  • listener.listen() and listener.unlisten() change the channels while the block runs; a notification received before unlisten() is returned.
  • A cancelled get() loses no notification: the next get() returns it.
  • When the server ends the connection (pg_terminate_backend(), a restart), the slot closes or its pool closes, get() returns the notifications received before, then raises InterfaceError in every task waiting in it. Notifications sent while no connection listens are lost; after listening again, re-read the state they reflect.
  • Leaving the block releases the slot; the slot closes a connection that still listens instead of returning it to the pool. A get() another task waits in raises InterfaceError.
python
async def follow_orders():
    pool = await adorm.settings.default_router().get_pool("default")
    delay = 0.1
    while True:
        try:
            async with adorm.listen("orders") as listener:
                delay = 0.1
                await reload_all_orders()              # what changed while nothing listened
                async for event in listener:
                    await refresh_order(int(event.payload))
        except adorm.InterfaceError:
            if pool.closed:
                return                                 # the application shuts down
            await asyncio.sleep(delay)                 # the connection was lost: listen again
            delay = min(delay * 2, 30)

A closed pool ends the loop: adorm.listen() and get() raise InterfaceError once the pool is closed.

A driver that does not declare notify in Capabilities.backend_events raises NotSupportedError before a slot is taken; inside Django's TestCase, whose transaction never commits, the Django driver refuses as well.

Cancellation outcomes ​

A cancelled request ends with a CancelledEvent:

  • started=False: the request was queued, or was cancelled before the slot handed it to the connection (for example while its connection options were set), and never reached the database;
  • started=True: it was cancelled in the driver connection while it ran; part of its work may have reached the database, whether it took effect is unknown, and an open transaction is unusable.
python
lease.requests.put_nowait(request := Request("execute", (slow_report,)))
lease.requests.cancel(request)
match await lease.events.get():
    case CancelledEvent(_, started=False): ...         # never ran
    case CancelledEvent(_, started=True): ...          # cancelled while running
    case ResultEvent() | ErrorEvent(): ...             # finished before the cancellation reached it

A request that finishes before the cancellation reaches it delivers its result or error instead; it has exactly one outcome. Cancelling the task that awaits lease.call() cancels its request the same way; the CancelledError it raises carries the request's CancellationOutcome, which the request's outcome event completes when it arrives after the caller has left (see cancellation).

JSON-safe form ​

Every event has a JSON-safe form for carrying it across a process boundary: event.to_dict() encodes it, Event.from_dict() decodes it, and errors travel by class, message and their adorm attributes (encode_error()).

Result values and payloads are encoded by their inferred type (encode_value()); to_dict(encode) and from_dict(data, decode) take a codec that encodes them by the types of the model schema instead.

Events by component ​

ComponentEmitsConsumes
Operationsnothingnothing
Sessions and bound modelsnothingoutcomes of their operations, through the runner or the transaction
Transactionsnothingoutcomes of their requests, on_commit
Pool, router and slotsoutcomes, on_commit, on_rollbackcallbacks and backend events of idle connections and of released leases (the pool's EventBus)
Connection profilesnothingnothing; events emitted during on_acquire / on_release follow the pool's rules
Driverscallbacks, backend eventsnothing
Django drivernotice, notify, connection_lost (on PostgreSQL with psycopg 3); Django's signals and on_commit() callbacks stay on the driver sidenothing
Native PostgreSQL drivernotice, notify, connection_lostnothing
adorm.listen()nothingnotify, connection_lost of its slot; passes other events to the pool's EventBus

Released under the MIT License.