feat(events): Database Event Channels extension (#291)

Adds the full SQLSpec Events extension: a unified event channel API with sync/async implementations, durable queue fallback, and native backends where available. This includes adapter-specific event backends, migration support, and framework integration for Litestar channels.

Author: cofin

.claude/agents/docs-vision.md

@@ -2,7 +2,7 @@
 name: docs-vision
 description: Documentation excellence, quality gate validation, and workspace cleanup specialist - ensures code quality, comprehensive docs, and clean workspace before completion
 tools: mcp__context7__resolve-library-id, mcp__context7__get-library-docs, WebSearch, Read, Write, Edit, Glob, Grep, Bash, Find, Task
-model: sonnet
+model: opus
 standards_uri: ../AGENTS.md#mandatory-code-quality-standards
 guides_root: ../docs/guides/
 workspace_root: ../specs/active/

.claude/agents/expert.md

@@ -2,7 +2,7 @@
 name: expert
 description: SQLSpec domain expert with comprehensive knowledge of database adapters, SQL parsing, type system, storage backends, and Litestar integration
 tools: mcp__context7__resolve-library-id, mcp__context7__get-library-docs, WebSearch, mcp__zen__analyze, mcp__zen__thinkdeep, mcp__zen__debug, Read, Write, Edit, Glob, Grep, Bash, Find, Task
-model: sonnet
+model: opus
 standards_uri: ../AGENTS.md#mandatory-code-quality-standards
 guides_root: ../docs/guides/
 workspace_root: ../specs/active/

.claude/agents/prd.md

@@ -2,7 +2,7 @@
 name: prd
 description: Product Requirements and Design agent for complex SQLSpec development spanning multiple files, adapters, and features
 tools: mcp__zen__planner, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, WebSearch, mcp__zen__consensus, Read, Write, Edit, Glob, Grep, Bash, Find, Task
-model: sonnet
+model: opus
 standards_uri: ../AGENTS.md#mandatory-code-quality-standards
 guides_root: ../docs/guides/
 workspace_root: ../specs/active/

.claude/agents/testing.md

@@ -2,7 +2,7 @@
 name: testing
 description: Comprehensive testing specialist for SQLSpec - creates unit tests, integration tests, fixtures, and validates test coverage across all database adapters
 tools: mcp__context7__resolve-library-id, mcp__context7__get-library-docs, Read, Write, Edit, Glob, Grep, Bash, Find, Task
-model: sonnet
+model: opus
 standards_uri: ../AGENTS.md#mandatory-code-quality-standards
 guides_root: ../docs/guides/
 workspace_root: ../specs/active/

.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
       - id: mixed-line-ending
       - id: trailing-whitespace
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.14.9"
+    rev: "v0.14.10"
     hooks:
       - id: ruff
         args: ["--fix"]

AGENTS.md

@@ -42,6 +42,7 @@ SQLSpec is currently in active development. The public API may change. Follow th
 
 - SQL validation and caching via sqlglot AST parsing
 - OpenTelemetry and Prometheus instrumentation hooks
+- Database event channels with native LISTEN/NOTIFY, Oracle AQ, and a portable queue fallback
 - Structured logging with correlation ID support
 - Migration CLI for schema versioning
 

README.md

@@ -42,6 +42,7 @@ SQLSpec is currently in active development. The public API may change. Follow th
 
 - SQL validation and caching via sqlglot AST parsing
 - OpenTelemetry and Prometheus instrumentation hooks
+- Database event channels with native LISTEN/NOTIFY, Oracle AQ, and a portable queue fallback
 - Structured logging with correlation ID support
 - Migration CLI for schema versioning
 

docs/PYPI_README.md

@@ -10,6 +10,20 @@ SQLSpec Changelog
 Recent Updates
 ==============
 
+Database Event Channels
+-----------------------
+
+- Added ``sqlspec.extensions.events.EventChannel`` with queue-backed publish/listen APIs that work uniformly across sync and async adapters.
+- Exposed ``SQLSpec.event_channel(config)`` so applications and agents can build channels directly from registered configs.
+- Introduced the ``events`` extension migrations (``ext_events_0001``) which create the durable queue table plus composite index.
+- Added the first native backend (AsyncPG LISTEN/NOTIFY) enabled via ``driver_features["events_backend"] = "listen_notify"``; the API automatically falls back to the queue backend for other adapters.
+- Introduced experimental Oracle Advanced Queuing support (sync adapters) via ``driver_features["events_backend"] = "advanced_queue"`` with automatic fallback when AQ is unavailable.
+- Documented configuration patterns (queue table naming, lease/retention windows, Oracle ``INMEMORY`` toggle, Postgres native mode) in :doc:`/guides/events/database-event-channels`.
+- Event telemetry now tracks ``events.publish``, ``events.publish.native``, ``events.deliver``, ``events.ack``, ``events.nack``, ``events.shutdown`` and listener lifecycle, so Prometheus/Otel exporters see event workloads alongside query metrics.
+- Added adapter-specific runtime hints (asyncmy, duckdb, bigquery/adbc) plus a ``poll_interval`` extension option so operators can tune leases and cadence per database.
+- Publishing, dequeue, ack, nack, and shutdown operations now emit ``sqlspec.events.*`` spans whenever ``extension_config["otel"]`` is enabled, giving full trace coverage without extra plumbing.
+- Documented adapter-specific guidance (asyncpg, psycopg, psqlpy, asyncmy, duckdb, oracle) and added a DuckDB integration test to cover the queue fallback path.
+
 v0.33.0 - Configuration Parameter Standardization (BREAKING CHANGE)
 --------------------------------------------------------------------
 

docs/changelog.rst

@@ -26,7 +26,8 @@ def test_example_10(tmp_path: Path) -> None:
         # start-example
         # Multiple value sets
         query = (
-            sql.insert("users")
+            sql
+            .insert("users")
             .columns("name", "email")
             .values("Alice", "[email protected]")
             .values("Bob", "[email protected]")