fix(events): use extension_config pattern for events configuration (#295)

Moves events configuration from `driver_features` to `extension_config` pattern, consistent with other extensions (litestar, adk, starlette, flask). Also adds consistent auto-migration inclusion for all extensions with `exclude_extensions` opt-out.

Author: cofin

AGENTS.md

@@ -865,18 +865,28 @@ The events extension provides database-agnostic pub/sub via two layers:
 **Backends** handle communication (LISTEN/NOTIFY, Oracle AQ, table polling):
 
 ```python
-# Backend selection via driver_features
-class AdapterDriverFeatures(TypedDict):
-    enable_events: NotRequired[bool]
-    events_backend: NotRequired[Literal["listen_notify", "listen_notify_durable", "table_queue", "advanced_queue"]]
-
-# Auto-detection in config __init__
-if "enable_events" not in driver_features:
-    driver_features["enable_events"] = extension_config.get("events") is not None
-if "events_backend" not in driver_features:
-    driver_features["events_backend"] = "listen_notify"  # or adapter-specific default
+# Backend selection via extension_config (NOT driver_features)
+config = AsyncpgConfig(
+    connection_config={"dsn": "postgresql://..."},
+    extension_config={
+        "events": {
+            "backend": "listen_notify_durable",  # Backend selection here
+            "queue_table": "event_queue_custom",
+            "lease_seconds": 60,
+        }
+    }
+)
 ```
 
+Available backends:
+- `listen_notify`: Real-time PostgreSQL LISTEN/NOTIFY (ephemeral, no migrations)
+- `table_queue`: Durable table-backed queue with retries (all adapters)
+- `listen_notify_durable`: Hybrid combining both (PostgreSQL only)
+- `advanced_queue`: Oracle Advanced Queueing
+
+PostgreSQL adapters (asyncpg, psycopg, psqlpy) default to `listen_notify`.
+All other adapters default to `table_queue`.
+
 **Stores** generate adapter-specific DDL for the queue table:
 
 ```python
@@ -916,10 +926,48 @@ def create_event_backend(
 
 - Backends implement `publish_async`, `dequeue_async`, `ack_async` (and sync variants)
 - Stores inherit from `BaseEventQueueStore` and override `_column_types()`
-- Use `driver_features` for backend selection, `extension_config["events"]` for settings
+- Use `extension_config["events"]["backend"]` for backend selection, other keys for settings
 - Always support `table_queue` fallback for databases without native pub/sub
 - Separate DDL execution for databases without transactional DDL (Spanner, BigQuery)
 
+**Auto-migration inclusion:**
+
+Extensions with migration support are automatically included in
+`migration_config["include_extensions"]` based on their settings:
+
+- **litestar**: Only when ``session_table`` is set (``True`` or custom name)
+- **adk**: When any adk settings are present
+- **events**: When any events settings are present
+
+Use `exclude_extensions` to opt out:
+
+```python
+# Auto-includes events migrations when extension_config["events"] is set
+config = AsyncpgConfig(
+    connection_config={"dsn": "postgresql://..."},
+    extension_config={"events": {"backend": "table_queue"}},
+)
+
+# Litestar with session storage - auto-includes migrations
+config = AsyncpgConfig(
+    connection_config={"dsn": "postgresql://..."},
+    extension_config={"litestar": {"session_table": True}},  # or "my_sessions"
+)
+
+# Litestar for DI only - no migrations needed
+config = AsyncpgConfig(
+    connection_config={"dsn": "postgresql://..."},
+    extension_config={"litestar": {"session_key": "db"}},  # No session_table = no migrations
+)
+
+# Exclude events migrations when using ephemeral backend
+config = AsyncpgConfig(
+    connection_config={"dsn": "postgresql://..."},
+    migration_config={"exclude_extensions": ["events"]},  # Skip queue table migration
+    extension_config={"events": {"backend": "listen_notify"}},
+)
+```
+
 **Reference implementation:** `sqlspec/extensions/events/`, `sqlspec/adapters/*/events/`
 
 ## Collaboration Guidelines

docs/guides/adapters/asyncpg.md

@@ -241,17 +241,15 @@ For comprehensive examples and migration guides, see:
 
 ## Event Channels
 
-- AsyncPG enables native LISTEN/NOTIFY support automatically by setting
-  `driver_features["events_backend"] = "listen_notify"` during config
-  construction. Call `spec.event_channel(config)` to obtain a channel—no
-  migrations are required.
+- AsyncPG defaults to native LISTEN/NOTIFY support (`backend="listen_notify"`).
+  Call `spec.event_channel(config)` to obtain a channel—no migrations required.
 - Publishing uses `connection.notify()` under the hood; consumers rely on
   `connection.add_listener()` with dedicated connections so the shared pool
   stays available for transactional work.
-- For durability and retries, set `driver_features["events_backend"] =
-  "listen_notify_durable"` and include the `events` extension migrations.
+- For durability and retries, set `extension_config={"events": {"backend": "listen_notify_durable"}}`
+  and include the `events` extension migrations.
 - Force the durable queue fallback (for deterministic testing or multi-tenant
-  workloads) by overriding `driver_features["events_backend"] = "table_queue"`
+  workloads) by setting `extension_config={"events": {"backend": "table_queue"}}`
   and including the `events` migrations.
 
 ## Common Issues

docs/guides/adapters/oracledb.md

@@ -902,9 +902,9 @@ For comprehensive examples and migration guides, see:
 
 ## Event Channels
 
-- Set `driver_features["events_backend"] = "advanced_queue"` to enable native
+- Set `extension_config={"events": {"backend": "advanced_queue"}}` to enable native
   Advanced Queuing support. Event publishing uses `connection.queue()` and
-  inherits the AQ options surfaced via `extension_config["events"]`
+  inherits the AQ options from `extension_config["events"]`
   (`aq_queue`, `aq_wait_seconds`, `aq_visibility`).
 - AQ requires DBA-provisioned queues plus enqueue/dequeue privileges. When the
   driver detects missing privileges it logs a warning and falls back to the

docs/guides/adapters/psqlpy.md

@@ -254,16 +254,15 @@ For comprehensive examples and migration guides, see:
 
 ## Event Channels
 
-- Psqlpy enables native LISTEN/NOTIFY by default
-  (`driver_features["events_backend"] = "listen_notify"`). Call
-  `spec.event_channel(config)` to publish or consume without migrations.
+- Psqlpy defaults to native LISTEN/NOTIFY support (`backend="listen_notify"`).
+  Call `spec.event_channel(config)` to obtain a channel—no migrations required.
 - Native listeners use the `Listener` API and a dedicated connection so the
   shared pool remains available for normal queries.
-- For durability and retries, set `driver_features["events_backend"] =
-  "listen_notify_durable"` and include the `events` extension migrations.
-- The queue-only fallback remains available by setting
-  `driver_features["events_backend"] = "table_queue"` alongside the
-  `events` migrations.
+- For durability and retries, set `extension_config={"events": {"backend": "listen_notify_durable"}}`
+  and include the `events` extension migrations.
+- Force the durable queue fallback (for deterministic testing or multi-tenant
+  workloads) by setting `extension_config={"events": {"backend": "table_queue"}}`
+  and including the `events` migrations.
 
 ## Best Practices
 

docs/guides/adapters/psycopg.md

@@ -133,16 +133,15 @@ For comprehensive examples and migration guides, see:
 
 ## Event Channels
 
-- Psycopg enables native LISTEN/NOTIFY support by default
-  (`driver_features["events_backend"] = "listen_notify"`). Call
-  `spec.event_channel(config)` to publish or consume without migrations.
-- Listeners run on dedicated connections so the pool remains available for
-  transactional work.
-- For durability and retries, set `driver_features["events_backend"] =
-  "listen_notify_durable"` and include the `events` extension migrations.
-- The queue-only fallback remains available by setting
-  `driver_features["events_backend"] = "table_queue"` alongside the
-  `events` migrations.
+- Psycopg defaults to native LISTEN/NOTIFY support (`backend="listen_notify"`).
+  Call `spec.event_channel(config)` to obtain a channel—no migrations required.
+- Publishing uses `connection.notify()` under the hood; consumers rely on
+  dedicated connections so the shared pool stays available for transactional work.
+- For durability and retries, set `extension_config={"events": {"backend": "listen_notify_durable"}}`
+  and include the `events` extension migrations.
+- Force the durable queue fallback (for deterministic testing or multi-tenant
+  workloads) by setting `extension_config={"events": {"backend": "table_queue"}}`
+  and including the `events` migrations.
 
 ## Common Issues
 

docs/guides/events/database-event-channels.md

@@ -15,17 +15,15 @@ from sqlspec.adapters.sqlite import SqliteConfig
 spec = SQLSpec()
 config = SqliteConfig(
     connection_config={"database": ":memory:"},
-    migration_config={
-        "script_location": "migrations",
-        "include_extensions": ["events"],
-    },
+    migration_config={"script_location": "migrations"},
     extension_config={
         "events": {
             "queue_table": "app_events",
         }
     },
 )
 spec.add_config(config)
+# Events migrations are auto-included when extension_config["events"] is present
 
 channel = spec.event_channel(config)
 channel.publish("notifications", {"type": "cache_invalidate", "key": "user:1"})
@@ -38,7 +36,7 @@ for message in channel.iter_events("notifications"):
 ## PostgreSQL native notifications
 
 All async PostgreSQL adapters (AsyncPG, Psycopg async, and Psqlpy) support
-native `LISTEN/NOTIFY` via `events_backend="listen_notify"`. When enabled,
+native `LISTEN/NOTIFY` via `extension_config["events"]["backend"] = "listen_notify"`. When enabled,
 events flow directly through PostgreSQL's notification system with no
 migrations required.
 
@@ -65,7 +63,7 @@ enabled as described below.
 
 ## Oracle Advanced Queuing (sync adapters)
 
-Set ``config.driver_features["events_backend"] = "advanced_queue"`` to opt into native AQ.
+Set ``extension_config["events"]["backend"] = "advanced_queue"`` to opt into native AQ.
 When enabled, ``EventChannel`` publishes JSON payloads via ``connection.queue`` and
 skips the durable table migrations. The backend currently targets synchronous drivers
 (async configs fall back to the queue extension automatically).
@@ -81,21 +79,22 @@ and transparently falls back to the table-backed queue backend.
 
 ## Enabling the events extension
 
-1. **Include the extension migrations**
+1. **Extension migrations are auto-included**
+
+   When `extension_config["events"]` is present, SQLSpec automatically
+   includes the events extension in `migration_config["include_extensions"]`.
+   Running `sqlspec upgrade` (or `config.migrate_up()`) applies
+   `ext_events_0001`, which creates the queue table and composite index.
+
+   To skip the migrations (e.g., for ephemeral `listen_notify` backend):
 
    ```python
    migration_config={
        "script_location": "migrations",
-       "include_extensions": ["events"],
+       "exclude_extensions": ["events"],  # Skip queue table migration
    }
    ```
 
-   When `extension_config["events"]` is present SQLSpec automatically
-   appends `"events"` to `include_extensions`, but setting it explicitly makes
-   the intent clear and mirrors other extension guides. Running
-   `sqlspec upgrade` (or `config.migrate_up()`) applies
-   `ext_events_0001`, which creates the queue table and composite index.
-
 2. **Provide extension settings (optional)**
 
    ```python
@@ -200,15 +199,19 @@ Manual iteration is also available via `channel.iter_events(...)` which yields
 
 | Option             | Default                 | Description |
 | ------------------ | ----------------------- | ----------- |
+| `backend`          | adapter-specific        | Backend implementation: `listen_notify`, `table_queue`, `listen_notify_durable`, or `advanced_queue`. |
 | `queue_table`      | `sqlspec_event_queue`   | Table name used by migrations and runtime. |
 | `lease_seconds`    | `30`                    | How long a consumer owns a message before it can be retried. |
 | `retention_seconds`| `86400`                 | How long acknowledged rows remain before automatic cleanup. |
 | `poll_interval`    | adapter-specific        | Default sleep window between dequeue attempts; see table below. |
 | `in_memory`        | `False`                 | Oracle-only flag that adds `INMEMORY PRIORITY HIGH` to the queue table. |
-| `aq_queue`         | `SQLSPEC_EVENTS_QUEUE`  | Native AQ queue name when `events_backend="advanced_queue"`. |
+| `aq_queue`         | `SQLSPEC_EVENTS_QUEUE`  | Native AQ queue name when `backend="advanced_queue"`. |
 | `aq_wait_seconds`  | `5`                     | Wait timeout (seconds) for AQ dequeue operations. |
 | `aq_visibility`    | *unset*                 | Optional visibility constant (e.g., `AQMSG_VISIBLE`). |
 
+To skip migrations for ephemeral backends (e.g., `listen_notify`), use
+`migration_config={"exclude_extensions": ["events"]}`.
+
 ### Adapter defaults
 
 `EventChannel` ships with tuned defaults per adapter so you rarely have to tweak the queue knobs. Override any value via `extension_config["events"]` when your workload differs from the defaults.
@@ -290,27 +293,28 @@ three backend types:
 | `advanced_queue` | Oracle Advanced Queuing | Enterprise Oracle deployments |
 | `table_queue` | Polling-based queue table | Universal fallback for any database |
 
-Configure the backend via `driver_features["events_backend"]`:
+Configure the backend via `extension_config["events"]["backend"]`:
 
 ```python
 from sqlspec.adapters.asyncpg import AsyncpgConfig
 
 # Native LISTEN/NOTIFY (default for PostgreSQL adapters)
 config = AsyncpgConfig(
     connection_config={"dsn": "postgresql://localhost/db"},
-    driver_features={"events_backend": "listen_notify"},
+    extension_config={"events": {"backend": "listen_notify"}},
 )
 
 # Hybrid: durable queue with NOTIFY wakeups
 config = AsyncpgConfig(
     connection_config={"dsn": "postgresql://localhost/db"},
-    driver_features={"events_backend": "listen_notify_durable"},
+    extension_config={"events": {"backend": "listen_notify_durable"}},
 )
 ```
 
 Queue-backed backends (`listen_notify_durable`, `table_queue`) require the
-events extension migrations. Ensure `migration_config["include_extensions"]`
-contains `"events"` before publishing or consuming.
+events extension migrations. When `extension_config["events"]` is present,
+SQLSpec auto-includes the migrations. For ephemeral `listen_notify` only,
+use `migration_config={"exclude_extensions": ["events"]}`.
 
 ### Event Queue Stores
 

sqlspec/adapters/adbc/config.py

@@ -2,7 +2,7 @@
 
 from collections.abc import Callable
 from contextlib import contextmanager
-from typing import TYPE_CHECKING, Any, ClassVar, Literal, TypedDict, cast
+from typing import TYPE_CHECKING, Any, ClassVar, TypedDict, cast
 
 from typing_extensions import NotRequired
 
@@ -141,8 +141,6 @@ class AdbcDriverFeatures(TypedDict):
     enable_cast_detection: NotRequired[bool]
     strict_type_coercion: NotRequired[bool]
     arrow_extension_types: NotRequired[bool]
-    enable_events: NotRequired[bool]
-    events_backend: NotRequired[Literal["table_queue"]]
 
 
 __all__ = ("AdbcConfig", "AdbcConnectionParams", "AdbcDriverFeatures")
@@ -205,10 +203,6 @@ def __init__(
         processed_driver_features.setdefault("strict_type_coercion", False)
         processed_driver_features.setdefault("arrow_extension_types", True)
 
-        # Auto-detect events support based on extension_config
-        processed_driver_features.setdefault("enable_events", "events" in (extension_config or {}))
-        processed_driver_features.setdefault("events_backend", "table_queue")
-
         if json_serializer is not None:
             statement_config = _apply_json_serializer_to_statement_config(statement_config, json_serializer)
 

sqlspec/adapters/aiosqlite/config.py

@@ -1,7 +1,7 @@
 """Aiosqlite database configuration."""
 
 from contextlib import asynccontextmanager
-from typing import TYPE_CHECKING, Any, ClassVar, Literal, TypedDict
+from typing import TYPE_CHECKING, Any, ClassVar, TypedDict
 
 from typing_extensions import NotRequired
 
@@ -82,8 +82,6 @@ class AiosqliteDriverFeatures(TypedDict):
     enable_custom_adapters: NotRequired[bool]
     json_serializer: "NotRequired[Callable[[Any], str]]"
     json_deserializer: "NotRequired[Callable[[str], Any]]"
-    enable_events: NotRequired[bool]
-    events_backend: NotRequired[Literal["table_queue"]]
 
 
 class AiosqliteConfig(AsyncDatabaseConfig["AiosqliteConnection", AiosqliteConnectionPool, AiosqliteDriver]):
@@ -145,10 +143,6 @@ def __init__(
         json_serializer = processed_driver_features.setdefault("json_serializer", to_json)
         json_deserializer = processed_driver_features.setdefault("json_deserializer", from_json)
 
-        # Auto-detect events support based on extension_config
-        processed_driver_features.setdefault("enable_events", "events" in (extension_config or {}))
-        processed_driver_features.setdefault("events_backend", "table_queue")
-
         base_statement_config = statement_config or aiosqlite_statement_config
         if json_serializer is not None:
             parameter_config = base_statement_config.parameter_config.with_json_serializers(

sqlspec/adapters/asyncmy/config.py

@@ -2,7 +2,7 @@
 
 from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
-from typing import TYPE_CHECKING, Any, ClassVar, Literal, TypedDict
+from typing import TYPE_CHECKING, Any, ClassVar, TypedDict
 
 import asyncmy
 from asyncmy.cursors import Cursor, DictCursor  # pyright: ignore
@@ -90,8 +90,6 @@ class AsyncmyDriverFeatures(TypedDict):
 
     json_serializer: NotRequired["Callable[[Any], str]"]
     json_deserializer: NotRequired["Callable[[str], Any]"]
-    enable_events: NotRequired[bool]
-    events_backend: NotRequired[Literal["table_queue"]]
 
 
 class AsyncmyConfig(AsyncDatabaseConfig[AsyncmyConnection, "AsyncmyPool", AsyncmyDriver]):  # pyright: ignore
@@ -144,10 +142,6 @@ def __init__(
         serializer = processed_driver_features.setdefault("json_serializer", to_json)
         deserializer = processed_driver_features.setdefault("json_deserializer", from_json)
 
-        # Auto-detect events support based on extension_config
-        processed_driver_features.setdefault("enable_events", "events" in (extension_config or {}))
-        processed_driver_features.setdefault("events_backend", "table_queue")
-
         base_statement_config = statement_config or build_asyncmy_statement_config(
             json_serializer=serializer, json_deserializer=deserializer
         )