sqlspec 0.59.0__tar.gz → 0.60.0__tar.gz

{sqlspec-0.59.0 → sqlspec-0.60.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlspec
-Version: 0.59.0
+Version: 0.60.0
 Summary: SQL Experiments in Python
 Project-URL: Discord, https://discord.gg/litestar
 Project-URL: Issue, https://github.com/litestar-org/sqlspec/issues/

{sqlspec-0.59.0 → sqlspec-0.60.0}/pyproject.toml

@@ -24,7 +24,7 @@ maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
 name = "sqlspec"
 readme = "README.md"
 requires-python = ">=3.10, <4.0"
-version = "0.59.0"
+version = "0.60.0"
 
 [project.urls]
 Discord = "https://discord.gg/litestar"
@@ -331,7 +331,7 @@ opt_level = "3"   # Maximum optimization (0-3)
 allow_dirty = true
 commit = false
 commit_args = "--no-verify"
-current_version = "0.59.0"
+current_version = "0.60.0"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"

{sqlspec-0.59.0 → sqlspec-0.60.0}/sqlspec/adapters/asyncpg/events/_hub.py

@@ -17,6 +17,7 @@ from weakref import WeakKeyDictionary
 
 from sqlspec.exceptions import EventChannelError
 from sqlspec.extensions.events import normalize_event_channel_name
+from sqlspec.extensions.events._buffer import enqueue_with_capacity, resolve_listener_queue_capacity
 from sqlspec.utils.logging import get_logger, log_with_context
 from sqlspec.utils.type_guards import has_add_listener
 
@@ -39,6 +40,7 @@ class AsyncpgListenerHub:
         "_config",
         "_connection",
         "_connection_cm",
+        "_listener_queue_capacity",
         "_lock",
         "_pool_destroying_registered",
         "_queues",
@@ -49,6 +51,7 @@ class AsyncpgListenerHub:
         self._backend_name = backend_name
         self._config = config
         self._lock = asyncio.Lock()
+        self._listener_queue_capacity = resolve_listener_queue_capacity(config)
         self._queues: dict[str, WeakKeyDictionary[asyncio.Task[Any], asyncio.Queue[str]]] = {}
         self._callbacks: dict[str, Callable[..., None]] = {}
         self._connection_cm: Any | None = None
@@ -106,9 +109,12 @@ class AsyncpgListenerHub:
         if queue is None:
             return None
         try:
-            return await asyncio.wait_for(queue.get(), timeout=poll_interval)
+            payload = await asyncio.wait_for(queue.get(), timeout=poll_interval)
         except asyncio.TimeoutError:
             return None
+        else:
+            self._record_queue_depth()
+            return payload
 
     async def shutdown(self) -> None:
         async with self._lock:
@@ -123,6 +129,7 @@ class AsyncpgListenerHub:
             self._callbacks.clear()
             self._connection = None
             self._connection_cm = None
+            self._record_queue_depth()
         if connection is not None:
             for channel in channels:
                 callback = callbacks.get(channel)
@@ -151,7 +158,7 @@ class AsyncpgListenerHub:
             return None
         queue = queues.get(task)
         if queue is None:
-            queue = asyncio.Queue()
+            queue = asyncio.Queue(maxsize=self._listener_queue_capacity or 0)
             queues[task] = queue
         return queue
 
@@ -207,7 +214,13 @@ class AsyncpgListenerHub:
         if queues is None:
             return
         for queue in list(queues.values()):
-            queue.put_nowait(payload)
+            if enqueue_with_capacity(queue, payload, self._listener_queue_capacity, empty_error=asyncio.QueueEmpty):
+                self._config.get_observability_runtime().increment_metric("events.listener.queue.dropped")
+        self._record_queue_depth()
+
+    def _record_queue_depth(self) -> None:
+        depth = sum(queue.qsize() for queues in self._queues.values() for queue in queues.values())
+        self._config.get_observability_runtime().record_metric("events.listener.queue.depth", depth)
 
 
 def _record_listener_lifecycle(config: "AsyncpgConfig", backend_name: str, status: str) -> None:

{sqlspec-0.59.0 → sqlspec-0.60.0}/sqlspec/adapters/psqlpy/events/_hub.py

@@ -18,6 +18,7 @@ from weakref import WeakKeyDictionary
 
 from sqlspec.core import SQL
 from sqlspec.extensions.events import normalize_event_channel_name
+from sqlspec.extensions.events._buffer import enqueue_with_capacity, resolve_listener_queue_capacity
 from sqlspec.utils.logging import get_logger, log_with_context
 from sqlspec.utils.type_guards import is_notification
 from sqlspec.utils.uuids import uuid4
@@ -79,6 +80,7 @@ class PsqlpyListenerHub:
         "_callbacks",
         "_config",
         "_listener",
+        "_listener_queue_capacity",
         "_listener_started",
         "_lock",
         "_pool_destroying_registered",
@@ -91,6 +93,7 @@ class PsqlpyListenerHub:
         self._backend_name = backend_name
         self._config = config
         self._lock = asyncio.Lock()
+        self._listener_queue_capacity = resolve_listener_queue_capacity(config)
         self._queues: dict[str, WeakKeyDictionary[asyncio.Task[Any], asyncio.Queue[str]]] = {}
         self._callbacks: dict[str, _PsqlpyHubCallback] = {}
         self._ready_events: dict[str, dict[str, asyncio.Event]] = {}
@@ -134,9 +137,12 @@ class PsqlpyListenerHub:
         if queue is None:
             return None
         try:
-            return await asyncio.wait_for(queue.get(), timeout=poll_interval)
+            payload = await asyncio.wait_for(queue.get(), timeout=poll_interval)
         except asyncio.TimeoutError:
             return None
+        else:
+            self._record_queue_depth()
+            return payload
 
     async def shutdown(self) -> None:
         async with self._lock:
@@ -149,6 +155,7 @@ class PsqlpyListenerHub:
             self._queues.clear()
             self._callbacks.clear()
             self._ready_events.clear()
+            self._record_queue_depth()
             self._listener = None
             self._listener_started = False
         if listener is not None:
@@ -178,7 +185,7 @@ class PsqlpyListenerHub:
             return None
         queue = queues.get(task)
         if queue is None:
-            queue = asyncio.Queue()
+            queue = asyncio.Queue(maxsize=self._listener_queue_capacity or 0)
             queues[task] = queue
         return queue
 
@@ -194,7 +201,7 @@ class PsqlpyListenerHub:
         queues: WeakKeyDictionary[asyncio.Task[Any], asyncio.Queue[str]] = WeakKeyDictionary()
         consumer_queue: asyncio.Queue[str] | None = None
         if consumer_task is not None:
-            consumer_queue = asyncio.Queue()
+            consumer_queue = asyncio.Queue(maxsize=self._listener_queue_capacity or 0)
             queues[consumer_task] = consumer_queue
         self._queues[channel] = queues
         self._callbacks[channel] = callback
@@ -284,7 +291,13 @@ class PsqlpyListenerHub:
         if queues is None:
             return
         for queue in list(queues.values()):
-            queue.put_nowait(payload)
+            if enqueue_with_capacity(queue, payload, self._listener_queue_capacity, empty_error=asyncio.QueueEmpty):
+                self._config.get_observability_runtime().increment_metric("events.listener.queue.dropped")
+        self._record_queue_depth()
+
+    def _record_queue_depth(self) -> None:
+        depth = sum(queue.qsize() for queues in self._queues.values() for queue in queues.values())
+        self._config.get_observability_runtime().record_metric("events.listener.queue.depth", depth)
 
 
 def _record_listener_lifecycle(config: "PsqlpyConfig", backend_name: str, status: str) -> None:

{sqlspec-0.59.0 → sqlspec-0.60.0}/sqlspec/adapters/psycopg/events/_hub.py

@@ -20,6 +20,7 @@ from weakref import WeakKeyDictionary
 from sqlspec.adapters.psycopg._typing import PsycopgComposed, PsycopgIdentifier, PsycopgSQL
 from sqlspec.exceptions import ImproperConfigurationError
 from sqlspec.extensions.events import normalize_event_channel_name
+from sqlspec.extensions.events._buffer import enqueue_with_capacity, resolve_listener_queue_capacity
 from sqlspec.utils.logging import get_logger, log_with_context
 from sqlspec.utils.type_guards import has_notifies
 
@@ -43,6 +44,7 @@ class PsycopgAsyncListenerHub:
         "_config",
         "_connection",
         "_connection_cm",
+        "_listener_queue_capacity",
         "_lock",
         "_pool_destroying_registered",
         "_pump_task",
@@ -55,6 +57,7 @@ class PsycopgAsyncListenerHub:
         self._backend_name = backend_name
         self._config = config
         self._lock = asyncio.Lock()
+        self._listener_queue_capacity = resolve_listener_queue_capacity(config)
         self._queues: dict[str, WeakKeyDictionary[asyncio.Task[Any], asyncio.Queue[str]]] = {}
         self._connection_cm: Any | None = None
         self._connection: Any | None = None
@@ -100,9 +103,12 @@ class PsycopgAsyncListenerHub:
         if queue is None:
             return None
         try:
-            return await asyncio.wait_for(queue.get(), timeout=poll_interval)
+            payload = await asyncio.wait_for(queue.get(), timeout=poll_interval)
         except asyncio.TimeoutError:
             return None
+        else:
+            self._record_queue_depth()
+            return payload
 
     async def shutdown(self) -> None:
         async with self._lock:
@@ -115,6 +121,7 @@ class PsycopgAsyncListenerHub:
             pump_task = self._pump_task
             channels = list(self._queues.keys())
             self._queues.clear()
+            self._record_queue_depth()
             self._connection = None
             self._connection_cm = None
             self._pump_task = None
@@ -146,7 +153,7 @@ class PsycopgAsyncListenerHub:
             return None
         queue = queues.get(task)
         if queue is None:
-            queue = asyncio.Queue()
+            queue = asyncio.Queue(maxsize=self._listener_queue_capacity or 0)
             queues[task] = queue
         return queue
 
@@ -235,7 +242,13 @@ class PsycopgAsyncListenerHub:
         if queues is None:
             return
         for queue in list(queues.values()):
-            queue.put_nowait(payload)
+            if enqueue_with_capacity(queue, payload, self._listener_queue_capacity, empty_error=asyncio.QueueEmpty):
+                self._config.get_observability_runtime().increment_metric("events.listener.queue.dropped")
+        self._record_queue_depth()
+
+    def _record_queue_depth(self) -> None:
+        depth = sum(queue.qsize() for queues in self._queues.values() for queue in queues.values())
+        self._config.get_observability_runtime().record_metric("events.listener.queue.depth", depth)
 
 
 class PsycopgSyncListenerHub:
@@ -253,6 +266,7 @@ class PsycopgSyncListenerHub:
         "_config",
         "_connection",
         "_connection_cm",
+        "_listener_queue_capacity",
         "_lock",
         "_pool_destroying_registered",
         "_queues",
@@ -265,6 +279,7 @@ class PsycopgSyncListenerHub:
         self._backend_name = backend_name
         self._config = config
         self._lock = threading.Lock()
+        self._listener_queue_capacity = resolve_listener_queue_capacity(config)
         self._queues: dict[str, WeakKeyDictionary[threading.Thread, stdlib_queue.Queue[str]]] = {}
         self._connection_cm: Any | None = None
         self._connection: Any | None = None
@@ -305,9 +320,12 @@ class PsycopgSyncListenerHub:
         if queue is None:
             return None
         try:
-            return queue.get(timeout=poll_interval)
+            payload = queue.get(timeout=poll_interval)
         except stdlib_queue.Empty:
             return None
+        else:
+            self._record_queue_depth()
+            return payload
 
     def shutdown(self) -> None:
         with self._lock:
@@ -318,6 +336,7 @@ class PsycopgSyncListenerHub:
             channels = list(self._queues.keys())
             worker_thread = self._worker_thread
             self._queues.clear()
+            self._record_queue_depth()
             self._connection_cm = None
             self._worker_thread = None
         if worker_thread is not None:
@@ -349,7 +368,7 @@ class PsycopgSyncListenerHub:
             thread = threading.current_thread()
             queue = queues.get(thread)
             if queue is None:
-                queue = stdlib_queue.Queue()
+                queue = stdlib_queue.Queue(maxsize=self._listener_queue_capacity or 0)
                 queues[thread] = queue
             return queue
 
@@ -467,7 +486,13 @@ class PsycopgSyncListenerHub:
                 return
             targets = list(queues.values())
         for queue in targets:
-            queue.put_nowait(payload)
+            if enqueue_with_capacity(queue, payload, self._listener_queue_capacity, empty_error=stdlib_queue.Empty):
+                self._config.get_observability_runtime().increment_metric("events.listener.queue.dropped")
+        self._record_queue_depth()
+
+    def _record_queue_depth(self) -> None:
+        depth = sum(queue.qsize() for queues in self._queues.values() for queue in queues.values())
+        self._config.get_observability_runtime().record_metric("events.listener.queue.depth", depth)
 
 
 def _record_listener_lifecycle(

{sqlspec-0.59.0 → sqlspec-0.60.0}/sqlspec/config.py

@@ -792,6 +792,9 @@ class EventsConfig(TypedDict):
     event_poll_interval: NotRequired[float]
     """Durable event reconciliation interval in seconds. Takes precedence over poll_interval."""
 
+    listener_queue_capacity: NotRequired[int]
+    """Maximum pending notifications per PostgreSQL listener consumer. Defaults to unbounded."""
+
     select_for_update: NotRequired[bool]
     """Use SELECT FOR UPDATE locking when claiming events. Defaults to False."""
 

sqlspec-0.60.0/sqlspec/extensions/events/_buffer.py

@@ -0,0 +1,38 @@
+"""Bounded event buffering helpers."""
+
+from typing import Any
+
+from sqlspec.exceptions import ImproperConfigurationError
+
+__all__ = ("enqueue_with_capacity", "resolve_listener_queue_capacity", "validate_queue_capacity")
+
+
+def validate_queue_capacity(
+    value: object, *, name: str, error_type: "type[Exception]" = ImproperConfigurationError
+) -> "int | None":
+    """Validate an optional positive queue capacity."""
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        msg = f"{name} must be a positive integer or None"
+        raise error_type(msg)
+    return value
+
+
+def resolve_listener_queue_capacity(config: Any) -> "int | None":
+    """Resolve and validate the PostgreSQL listener queue capacity."""
+    settings = getattr(config, "extension_config", {}).get("events", {})
+    return validate_queue_capacity(settings.get("listener_queue_capacity"), name="listener_queue_capacity")
+
+
+def enqueue_with_capacity(queue: Any, item: object, capacity: "int | None", *, empty_error: "type[Exception]") -> bool:
+    """Enqueue an item, evicting the oldest item when capacity is reached."""
+    dropped = False
+    if capacity is not None and queue.qsize() >= capacity:
+        try:
+            queue.get_nowait()
+            dropped = True
+        except empty_error:
+            pass
+    queue.put_nowait(item)
+    return dropped

{sqlspec-0.59.0 → sqlspec-0.60.0}/sqlspec/extensions/events/_channel.py

@@ -12,6 +12,7 @@ from time import perf_counter
 from typing import TYPE_CHECKING, Any, cast
 
 from sqlspec.exceptions import ImproperConfigurationError, MissingDependencyError
+from sqlspec.extensions.events._buffer import validate_queue_capacity
 from sqlspec.extensions.events._hints import get_runtime_hints, resolve_adapter_name
 from sqlspec.extensions.events._models import EventMessage
 from sqlspec.extensions.events._names import normalize_event_channel_name
@@ -194,6 +195,7 @@ class SyncEventChannel:
             msg = "SyncEventChannel requires a sync configuration"
             raise ImproperConfigurationError(msg)
         extension_settings: dict[str, Any] = dict(config.extension_config.get("events", {}))
+        validate_queue_capacity(extension_settings.get("listener_queue_capacity"), name="listener_queue_capacity")
         self._adapter_name = resolve_adapter_name(config)
         hints = get_runtime_hints(self._adapter_name, config)
         self._event_poll_interval = resolve_event_poll_interval(
@@ -463,6 +465,7 @@ class AsyncEventChannel:
             msg = "AsyncEventChannel requires an async configuration"
             raise ImproperConfigurationError(msg)
         extension_settings: dict[str, Any] = dict(config.extension_config.get("events", {}))
+        validate_queue_capacity(extension_settings.get("listener_queue_capacity"), name="listener_queue_capacity")
         self._adapter_name = resolve_adapter_name(config)
         hints = get_runtime_hints(self._adapter_name, config)
         self._event_poll_interval = resolve_event_poll_interval(

{sqlspec-0.59.0 → sqlspec-0.60.0}/sqlspec/extensions/events/_store.py

@@ -4,6 +4,7 @@ from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypeVar, cast
 
 from sqlspec.exceptions import ImproperConfigurationError
+from sqlspec.extensions.events._buffer import validate_queue_capacity
 from sqlspec.extensions.events._names import normalize_event_channel_name, normalize_queue_table_name
 from sqlspec.migrations.schema import SchemaEnsureResult, SchemaTarget, ensure_schema_async, ensure_schema_sync
 
@@ -39,6 +40,7 @@ class BaseEventQueueStore(ABC, Generic[ConfigT]):
         "create_schema",
         "event_poll_interval",
         "lease_seconds",
+        "listener_queue_capacity",
         "manage_schema",
         "migrations_path",
         "poll_interval",
@@ -115,6 +117,7 @@ class BaseEventQueueStore(ABC, Generic[ConfigT]):
             keys = ", ".join(repr(key) for key in unsupported)
             msg = f"Unsupported events configuration key(s) for {adapter}: {keys}"
             raise ImproperConfigurationError(msg)
+        validate_queue_capacity(self._extension_settings.get("listener_queue_capacity"), name="listener_queue_capacity")
 
     def _schema_management_flags(self) -> "tuple[bool, bool]":
         """Return automatic-management and missing-table creation flags."""

{sqlspec-0.59.0 → sqlspec-0.60.0}/sqlspec/extensions/litestar/channels.py

@@ -8,6 +8,7 @@ from typing import TYPE_CHECKING, Any
 
 from litestar.channels.backends.base import ChannelsBackend
 
+from sqlspec.extensions.events._buffer import enqueue_with_capacity, validate_queue_capacity
 from sqlspec.utils.logging import get_logger
 
 if TYPE_CHECKING:
@@ -29,7 +30,12 @@ class SQLSpecChannelsBackend(ChannelsBackend):
     """
 
     def __init__(
-        self, event_channel: "AsyncEventChannel", *, channel_prefix: str = "litestar", poll_interval: float = 0.2
+        self,
+        event_channel: "AsyncEventChannel",
+        *,
+        channel_prefix: str = "litestar",
+        poll_interval: float = 0.2,
+        output_queue_capacity: int | None = None,
     ) -> None:
         if not _IDENTIFIER_PATTERN.match(channel_prefix):
             msg = f"channel_prefix must be a valid identifier, got: {channel_prefix!r}"
@@ -37,10 +43,14 @@ class SQLSpecChannelsBackend(ChannelsBackend):
         if poll_interval <= 0:
             msg = "poll_interval must be greater than zero"
             raise ValueError(msg)
+        self._output_queue_capacity = validate_queue_capacity(
+            output_queue_capacity, name="output_queue_capacity", error_type=ValueError
+        )
         self._event_channel = event_channel
         self._channel_prefix = channel_prefix
         self._poll_interval = poll_interval
         self._output_queue: asyncio.Queue[tuple[str, bytes]] | None = None
+        self._dropped_message_count = 0
         self._shutdown = asyncio.Event()
         self._tasks: dict[str, asyncio.Task[None]] = {}
         self._to_db_channel: dict[str, str] = {}
@@ -61,8 +71,19 @@ class SQLSpecChannelsBackend(ChannelsBackend):
             await asyncio.gather(*tasks, return_exceptions=True)
         self._to_db_channel.clear()
         self._to_litestar_channel.clear()
+        self._output_queue = None
         await self._event_channel.shutdown()
 
+    @property
+    def output_queue_depth(self) -> int:
+        """Return the number of buffered channel messages."""
+        return self._output_queue.qsize() if self._output_queue is not None else 0
+
+    @property
+    def dropped_message_count(self) -> int:
+        """Return the cumulative number of messages dropped due to overflow."""
+        return self._dropped_message_count
+
     async def publish(self, data: bytes, channels: "Iterable[str]") -> None:
         await self.publish_many((data,), channels)
 
@@ -152,7 +173,10 @@ class SQLSpecChannelsBackend(ChannelsBackend):
                     await self._event_channel.ack(message.event_id)
                     continue
                 assert self._output_queue is not None
-                await self._output_queue.put((channel, decoded))
+                if enqueue_with_capacity(
+                    self._output_queue, (channel, decoded), self._output_queue_capacity, empty_error=asyncio.QueueEmpty
+                ):
+                    self._dropped_message_count += 1
                 await self._event_channel.ack(message.event_id)
         except asyncio.CancelledError:
             raise

{sqlspec-0.59.0 → sqlspec-0.60.0}/tests/integration/extensions/litestar/test_channels_backend.py

@@ -1,8 +1,10 @@
 import asyncio
 import tempfile
+from types import SimpleNamespace
 from typing import Any, cast
 
 import msgspec.json
+import pytest
 from litestar.channels.plugin import ChannelsPlugin
 
 from sqlspec.adapters.aiosqlite.config import AiosqliteConfig
@@ -27,6 +29,24 @@ class _RecordingEventChannel:
         return [f"event-{index}" for index in range(len(events))]
 
 
+class _StreamingEventChannel:
+    def __init__(self, payloads: list[dict[str, str]]) -> None:
+        self.payloads = payloads
+        self.acked: list[str] = []
+        self.shutdown_calls = 0
+
+    async def iter_events(self, _channel: str, *, poll_interval: float) -> "Any":
+        _ = poll_interval
+        for index, payload in enumerate(self.payloads):
+            yield SimpleNamespace(event_id=str(index), payload=payload)
+
+    async def ack(self, event_id: str) -> None:
+        self.acked.append(event_id)
+
+    async def shutdown(self) -> None:
+        self.shutdown_calls += 1
+
+
 async def test_litestar_channels_backend_database_roundtrip(tmp_path: "Any") -> None:
     migrations = tmp_path / "migrations"
     migrations.mkdir()
@@ -91,3 +111,45 @@ async def test_litestar_channels_backend_groups_multiple_payloads_and_channels()
         (backend._db_channel_name("alpha"), "c2Vjb25k"),
         (backend._db_channel_name("beta"), "c2Vjb25k"),
     ]
+
+
+@pytest.mark.parametrize("capacity", [True, False, 0, -1, 1.5, "1"])
+def test_litestar_channels_backend_rejects_invalid_output_capacity(capacity: object) -> None:
+    with pytest.raises(ValueError, match="output_queue_capacity must be a positive integer"):
+        SQLSpecChannelsBackend(cast("Any", _RecordingEventChannel()), output_queue_capacity=capacity)  # type: ignore[arg-type]
+
+
+async def test_litestar_channels_backend_drops_oldest_and_preserves_acknowledgements() -> None:
+    event_channel = _StreamingEventChannel([
+        {"data_b64": "Zmlyc3Q="},
+        {"data_b64": "c2Vjb25k"},
+        {"data_b64": "dGhpcmQ="},
+    ])
+    backend = SQLSpecChannelsBackend(cast("Any", event_channel), output_queue_capacity=2)
+    await backend.on_startup()
+
+    await backend._stream_channel("alerts", backend._db_channel_name("alerts"))
+
+    assert backend.output_queue_depth == 2
+    assert backend.dropped_message_count == 1
+    assert event_channel.acked == ["0", "1", "2"]
+    stream = backend.stream_events()
+    assert await anext(stream) == ("alerts", b"second")
+    assert await anext(stream) == ("alerts", b"third")
+    assert backend.output_queue_depth == 0
+
+    await backend.on_shutdown()
+    assert backend.output_queue_depth == 0
+    assert backend.dropped_message_count == 1
+
+
+async def test_litestar_channels_backend_malformed_payload_does_not_count_as_overflow() -> None:
+    event_channel = _StreamingEventChannel([{"invalid": "payload"}])
+    backend = SQLSpecChannelsBackend(cast("Any", event_channel), output_queue_capacity=1)
+    await backend.on_startup()
+
+    await backend._stream_channel("alerts", backend._db_channel_name("alerts"))
+
+    assert backend.output_queue_depth == 0
+    assert backend.dropped_message_count == 0
+    assert event_channel.acked == ["0"]

{sqlspec-0.59.0 → sqlspec-0.60.0}/tests/unit/extensions/test_events/test_adapter_stores.py

@@ -1,6 +1,9 @@
 # pyright: reportPrivateUsage=false
 """Unit tests for adapter-specific event queue stores and DDL generation."""
 
+import importlib
+import inspect
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 import pytest
@@ -16,6 +19,25 @@ else:
     BaseEventQueueStoreBase = BaseEventQueueStore
 
 
+def test_all_adapter_event_stores_declare_listener_queue_capacity_behavior() -> None:
+    adapter_root = Path(__file__).parents[4] / "sqlspec" / "adapters"
+    store_paths = sorted(adapter_root.glob("*/events/store.py"))
+    discovered: set[str] = set()
+
+    for store_path in store_paths:
+        adapter_name = store_path.parents[1].name
+        module = importlib.import_module(f"sqlspec.adapters.{adapter_name}.events.store")
+        for _, store_type in inspect.getmembers(module, inspect.isclass):
+            if store_type is BaseEventQueueStore or not issubclass(store_type, BaseEventQueueStore):
+                continue
+            if store_type.__module__ != module.__name__:
+                continue
+            discovered.add(adapter_name)
+            assert "listener_queue_capacity" in store_type.extension_config_options
+
+    assert discovered == {path.parents[1].name for path in store_paths}
+
+
 def test_asyncmy_store_column_types() -> None:
     """Asyncmy store uses MySQL-compatible column types."""
     pytest.importorskip("asyncmy")

{sqlspec-0.59.0 → sqlspec-0.60.0}/tests/unit/extensions/test_events/test_events_config.py

@@ -8,6 +8,8 @@ import pytest
 
 from sqlspec.adapters.sqlite import SqliteConfig
 from sqlspec.config import EventsConfig
+from sqlspec.exceptions import ImproperConfigurationError
+from sqlspec.extensions.events import SyncEventChannel
 
 
 def test_events_backend_literal_uses_canonical_transport_names() -> None:
@@ -20,6 +22,28 @@ def test_events_backend_literal_uses_canonical_transport_names() -> None:
     assert set(backend_values) == {"notify", "notify_queue", "poll_queue", "aq", "txeventq"}
 
 
+@pytest.mark.parametrize("capacity", [True, False, 0, -1, 1.5, "1", []])
+def test_listener_queue_capacity_rejects_non_positive_integers(tmp_path: Path, capacity: object) -> None:
+    config = SqliteConfig(
+        connection_config={"database": str(tmp_path / "events-capacity.db")},
+        extension_config={"events": {"listener_queue_capacity": capacity}},  # type: ignore[typeddict-item]
+    )
+
+    with pytest.raises(ImproperConfigurationError, match="listener_queue_capacity must be a positive integer"):
+        SyncEventChannel(config)
+
+
+def test_listener_queue_capacity_is_accepted_by_poll_queue_store(tmp_path: Path) -> None:
+    from sqlspec.adapters.sqlite.events.store import SqliteEventQueueStore
+
+    config = SqliteConfig(
+        connection_config={"database": str(tmp_path / "events-capacity.db")},
+        extension_config={"events": {"listener_queue_capacity": 4}},
+    )
+
+    assert SqliteEventQueueStore(config).settings["listener_queue_capacity"] == 4
+
+
 _POSTGRES_DRIVER_FEATURES = (
     ("sqlspec.adapters.asyncpg.config", "AsyncpgDriverFeatures"),
     ("sqlspec.adapters.psycopg.config", "PsycopgDriverFeatures"),