Skip to content

Events & Channels Extension

from sqlspec.extensions.events import (
    AsyncEventBackendProtocol,
    AsyncEventChannel,
    AsyncEventListener,
    AsyncTableEventQueue,
    BaseEventQueueStore,
    EventMessage,
    EventRuntimeHints,
    SyncEventBackendProtocol,
    SyncEventChannel,
    SyncEventListener,
    SyncTableEventQueue,
    build_queue_backend,
    decode_notify_payload,
    encode_notify_payload,
    fits_notify_payload,
    get_runtime_hints,
    measure_notify_payload,
)

Database-native pub/sub (LISTEN/NOTIFY, Oracle Advanced Queuing) and durable table-backed event queues across all supported adapters. Adapter-specific EventQueueStore and native EventsBackend classes are documented on each Database Adapter page. See the Event Channels Guide for usage examples.

Event Channels & Listeners

SyncEventChannel

Event channel for synchronous database configurations.

publish

publish(channel, payload, metadata=None)

Publish an event to a channel.

iter_events

iter_events(channel, *, event_poll_interval=None, poll_interval=None)

Yield events as they become available.

listen

listen(
    channel,
    handler,
    *,
    event_poll_interval=None,
    poll_interval=None,
    auto_ack=True,
)

Start a background thread that invokes handler for each event.

ack

ack(event_id)

Acknowledge an event.

nack

nack(event_id)

Return a leased event to the queue with exponential backoff, or mark it failed at max_attempts.

shutdown

shutdown()

Shutdown the event channel and release backend resources.