Events & Channels Extension¶

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

Database-native pub/sub (LISTEN/NOTIFY, Oracle Advanced Queuing) and durable table-backed event queues across all 20 adapters. 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 an event to the queue for redelivery.

shutdown ¶

shutdown()

Shutdown the event channel and release backend resources.

AsyncEventChannel ¶

Event channel for asynchronous 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 an async task that delivers events to handler.

ack ¶

ack(event_id)

Acknowledge an event.

nack ¶

nack(event_id)

Return an event to the queue for redelivery.

shutdown ¶

shutdown()

Shutdown the event channel and release backend resources.

SyncEventListener ¶

Represents a running sync listener thread.

stop ¶

stop()

Signal the listener to stop and join the thread.

AsyncEventListener ¶

Represents a running async listener task.

stop ¶

stop()

Signal the listener to stop and await task completion.

EventMessage ¶

Structured payload delivered to event handlers.

Durable Table Queues & Stores¶

SyncTableEventQueue ¶

Bases: _BaseTableEventQueue

Sync table queue implementation.

AsyncTableEventQueue ¶

Bases: _BaseTableEventQueue

Async table queue implementation.

BaseEventQueueStore ¶

Bases: ABC, Generic[ConfigT]

Base class for adapter-specific event queue DDL generators.

This class provides a hook-based pattern for DDL generation. Adapters only need to override _column_types() and optionally any hook methods for dialect-specific variations:

_string_type(length): String type syntax (default: VARCHAR(N))
_integer_type(): Integer type syntax (default: INTEGER)
_timestamp_default(): Timestamp default expression (default: CURRENT_TIMESTAMP)
_primary_key_syntax(): Inline PRIMARY KEY clause (default: empty, PK on column)
_table_clause(): Additional table options (default: empty)

For complex dialects (Oracle PL/SQL, BigQuery CLUSTER BY), adapters may override _table_ddl() directly.

create_statements ¶

create_statements()

Return statements required to create the queue table and indexes.

drop_statements ¶

drop_statements()

Return statements required to drop queue artifacts.

build_queue_backend ¶

build_queue_backend(
    config, extension_settings=None, *, adapter_name=None, hints=None
)

Build a table queue backend using adapter hints and extension overrides.

Runtime Hints, Protocols & Payload Helpers¶

EventRuntimeHints ¶

Adapter-specific defaults for event polling and leases.

get_runtime_hints ¶

get_runtime_hints(adapter, config=None)

Return runtime hints provided by the adapter configuration.

SyncEventBackendProtocol ¶

Bases: Protocol

Protocol for sync event backends.

All sync event backends (native or queue-based) must implement these methods.

AsyncEventBackendProtocol ¶

Bases: Protocol

Protocol for async event backends.

All async event backends (native or queue-based) must implement these methods.

encode_notify_payload ¶

encode_notify_payload(event_id, payload, metadata)

Encode event data as JSON for NOTIFY payload.

Raises:

Type	Description
`EventChannelError`	If the encoded envelope exceeds the PostgreSQL notification budget.

decode_notify_payload ¶

decode_notify_payload(channel, payload)

Decode JSON payload from NOTIFY into an EventMessage.