sqlalchemy-foundation-kit 0.3.0__tar.gz → 0.4.0__tar.gz

{sqlalchemy_foundation_kit-0.3.0 → sqlalchemy_foundation_kit-0.4.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.4.0](https://github.com/bedrock-python/sqlalchemy-foundation-kit/compare/sqlalchemy-foundation-kit-v0.3.0...sqlalchemy-foundation-kit-v0.4.0) (2026-09-07)
+
+
+### Features
+
+* measure the wait for a pool connection, and count pool checkout timeouts ([#27](https://github.com/bedrock-python/sqlalchemy-foundation-kit/issues/27)) ([78c9d7e](https://github.com/bedrock-python/sqlalchemy-foundation-kit/commit/78c9d7e2c05052090276bce08219047849cd6dbb))
+
 ## [0.3.0](https://github.com/bedrock-python/sqlalchemy-foundation-kit/compare/sqlalchemy-foundation-kit-v0.2.1...sqlalchemy-foundation-kit-v0.3.0) (2026-09-07)
 
 

{sqlalchemy_foundation_kit-0.3.0 → sqlalchemy_foundation_kit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlalchemy-foundation-kit
-Version: 0.3.0
+Version: 0.4.0
 Summary: Foundation layer for SQLAlchemy-based services with UoW, session management, and observability
 Project-URL: Repository, https://github.com/bedrock-python/sqlalchemy-foundation-kit
 Project-URL: Documentation, https://bedrock-python.github.io/sqlalchemy-foundation-kit/
@@ -494,7 +494,7 @@ from sqlalchemy_foundation_kit.contrib.settings import (
 from sqlalchemy_foundation_kit.contrib.metrics import PostgresMetrics
 ```
 - `PostgresMetrics` — Prometheus metrics for connection pool
-- Tracks: pool size, checked out connections, checkout duration, errors
+- Tracks: pool size, checked out connections, checkout wait, held duration, timeouts, errors
 
 #### `contrib.di` (requires `[dishka]`)
 ```python

{sqlalchemy_foundation_kit-0.3.0 → sqlalchemy_foundation_kit-0.4.0}/README.md

@@ -243,7 +243,7 @@ from sqlalchemy_foundation_kit.contrib.settings import (
 from sqlalchemy_foundation_kit.contrib.metrics import PostgresMetrics
 ```
 - `PostgresMetrics` — Prometheus metrics for connection pool
-- Tracks: pool size, checked out connections, checkout duration, errors
+- Tracks: pool size, checked out connections, checkout wait, held duration, timeouts, errors
 
 #### `contrib.di` (requires `[dishka]`)
 ```python

{sqlalchemy_foundation_kit-0.3.0 → sqlalchemy_foundation_kit-0.4.0}/sqlalchemy_foundation_kit/__init__.py

@@ -31,6 +31,7 @@ from .config import (
 # Protocols
 from .protocols import (
     CheckoutRecorder,
+    CheckoutWaitRecorder,
     ErrorRecorder,
     PoolStatsRecorder,
     PostgresMetricsProtocol,
@@ -64,7 +65,7 @@ from .uow import (
 try:
     __version__ = version("sqlalchemy-foundation-kit")
 except PackageNotFoundError:  # pragma: no cover
-    __version__ = "0.3.0"
+    __version__ = "0.4.0"
 
 __all__ = [  # noqa: RUF022
     # Base ORM
@@ -89,6 +90,7 @@ __all__ = [  # noqa: RUF022
     "QuerySettingsProtocol",
     # Protocols
     "CheckoutRecorder",
+    "CheckoutWaitRecorder",
     "ErrorRecorder",
     "PoolStatsRecorder",
     "PostgresMetricsProtocol",

sqlalchemy_foundation_kit-0.4.0/sqlalchemy_foundation_kit/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

{sqlalchemy_foundation_kit-0.3.0 → sqlalchemy_foundation_kit-0.4.0}/sqlalchemy_foundation_kit/contrib/metrics/postgres.py

@@ -11,7 +11,7 @@ try:
 except ImportError:
     HAS_PROMETHEUS = False
 
-# Default buckets for connection checkout duration (seconds)
+# Default buckets for how long a connection was held (seconds)
 CONNECTION_CHECKOUT_BUCKETS: tuple[float, ...] = (
     0.001,
     0.005,
@@ -26,6 +26,25 @@ CONNECTION_CHECKOUT_BUCKETS: tuple[float, ...] = (
     5.0,
 )
 
+# Default buckets for the wait for a connection from the pool (seconds). The range runs to
+# 30 s, the default ``pool_timeout``, so a saturated pool fills the top buckets instead of
+# collapsing into +Inf just when the histogram is worth reading.
+CONNECTION_WAIT_BUCKETS: tuple[float, ...] = (
+    0.001,
+    0.005,
+    0.01,
+    0.025,
+    0.05,
+    0.1,
+    0.25,
+    0.5,
+    1.0,
+    2.5,
+    5.0,
+    10.0,
+    30.0,
+)
+
 
 def _check_prometheus() -> None:
     """Check if prometheus-client is installed."""
@@ -43,12 +62,19 @@ class PostgresMetrics:
         - postgres_db_pool_size: Current database connection pool size.
         - postgres_db_pool_checked_out: Number of connections currently checked out.
         - postgres_db_pool_overflow: Number of connections over pool_size (within max_overflow).
-        - postgres_db_connection_checkout_duration_seconds: Time to acquire connection from pool.
+        - postgres_db_connection_checkout_wait_seconds: Time a caller waited for a connection.
+        - postgres_db_connection_held_duration_seconds: Time a connection was held by its caller.
+        - postgres_db_connection_checkout_duration_seconds: Deprecated alias of the held duration,
+          published unchanged for one more minor release.
         - postgres_db_connection_timeouts_total: Number of connection checkout timeouts.
         - postgres_db_connection_errors_total: Number of connection errors.
 
     Labels:
         - error_type: Type of connection error (for errors_total).
+
+    The wait histogram and the timeout counter are fed by the instrumented pool class the
+    session manager builds, so they only move on an engine created by
+    ``AsyncSessionManager`` (or one whose pool went through ``instrument_pool_class``).
     """
 
     def __init__(self, prefix: str | None = None) -> None:
@@ -74,9 +100,19 @@ class PostgresMetrics:
             _make_metric_name("postgres_db_pool_overflow", prefix),
             "Number of connections over pool_size (within max_overflow)",
         )
+        self.connection_checkout_wait = Histogram(
+            _make_metric_name("postgres_db_connection_checkout_wait_seconds", prefix),
+            "Time a caller waited to acquire a connection from the pool",
+            buckets=list(CONNECTION_WAIT_BUCKETS),
+        )
+        self.connection_held_duration = Histogram(
+            _make_metric_name("postgres_db_connection_held_duration_seconds", prefix),
+            "Time a connection was held by its caller, from checkout to checkin",
+            buckets=list(CONNECTION_CHECKOUT_BUCKETS),
+        )
         self.connection_checkout_duration = Histogram(
             _make_metric_name("postgres_db_connection_checkout_duration_seconds", prefix),
-            "Time to acquire connection from pool",
+            "Deprecated: held duration, published under its old name. Use postgres_db_connection_held_duration_seconds",
             buckets=list(CONNECTION_CHECKOUT_BUCKETS),
         )
         self.connection_timeouts_total = Counter(
@@ -104,9 +140,29 @@ class PostgresMetrics:
         self,
         duration: float,
     ) -> None:
-        """Record a database connection checkout from the pool."""
+        """Record how long a connection was held, from checkout to checkin.
+
+        Observed into ``postgres_db_connection_held_duration_seconds`` and, until the
+        deprecated name is dropped, into ``postgres_db_connection_checkout_duration_seconds``
+        as well.
+        """
+        self.connection_held_duration.observe(duration)
         self.connection_checkout_duration.observe(duration)
 
+    def record_checkout_wait(
+        self,
+        duration: float,
+        timed_out: bool = False,
+    ) -> None:
+        """Record the wait for a connection from the pool, and count a pool timeout.
+
+        A pool checkout timeout is raised before any DBAPI call, so it never reaches the
+        engine's ``handle_error`` listener; this is the only place it is counted.
+        """
+        self.connection_checkout_wait.observe(duration)
+        if timed_out:
+            self.connection_timeouts_total.inc()
+
     def record_error(
         self,
         error_type: str,

{sqlalchemy_foundation_kit-0.3.0 → sqlalchemy_foundation_kit-0.4.0}/sqlalchemy_foundation_kit/protocols/__init__.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 from .metrics import (
     CheckoutRecorder,
+    CheckoutWaitRecorder,
     ErrorRecorder,
     PoolStatsRecorder,
     PostgresMetricsProtocol,
@@ -15,6 +16,7 @@ from .metrics import (
 
 __all__ = [
     "CheckoutRecorder",
+    "CheckoutWaitRecorder",
     "ErrorRecorder",
     "PoolStatsRecorder",
     "PostgresMetricsProtocol",

{sqlalchemy_foundation_kit-0.3.0 → sqlalchemy_foundation_kit-0.4.0}/sqlalchemy_foundation_kit/protocols/metrics.py

@@ -7,7 +7,7 @@ the narrow protocols selectively (e.g., only record errors), and
 
 from __future__ import annotations
 
-from typing import Protocol
+from typing import Protocol, runtime_checkable
 
 
 class PoolStatsRecorder(Protocol):
@@ -30,13 +30,39 @@ class PoolStatsRecorder(Protocol):
 
 
 class CheckoutRecorder(Protocol):
-    """Capability protocol for recording connection checkout duration."""
+    """Capability protocol for recording how long a connection was held."""
 
     def record_checkout(self, duration: float) -> None:
-        """Record a database connection checkout from the pool.
+        """Record a completed database connection checkout.
 
         Args:
-            duration: Time taken to acquire the connection from the pool, in seconds.
+            duration: Time between the connection leaving the pool and coming back to it,
+                in seconds — how long the caller *held* it, which is the query time seen
+                from the pool. The time a caller spent *waiting* for it is
+                :class:`CheckoutWaitRecorder`.
+        """
+        ...
+
+
+@runtime_checkable
+class CheckoutWaitRecorder(Protocol):
+    """Capability protocol for recording the wait for a connection from the pool.
+
+    Deliberately not part of :class:`PostgresMetricsProtocol`: a metrics object written
+    against the three older capabilities stays valid and simply publishes no wait series.
+    The session manager tests for this protocol with ``isinstance`` and instruments the
+    pool class only when it is satisfied, which is what ``runtime_checkable`` is for here.
+    """
+
+    def record_checkout_wait(self, duration: float, timed_out: bool = False) -> None:
+        """Record the time a caller spent acquiring a connection from the pool.
+
+        Args:
+            duration: Seconds spent inside ``pool.connect()`` — the queue wait, and the
+                pre-ping round trip and connect handshake when the pool had to grow.
+            timed_out: True if the wait ended in ``sqlalchemy.exc.TimeoutError`` rather
+                than in a connection. This is the pool checkout timeout; it is raised
+                before any DBAPI call and so never reaches the engine's ``handle_error``.
         """
         ...
 
@@ -60,10 +86,15 @@ class PostgresMetricsProtocol(PoolStatsRecorder, CheckoutRecorder, ErrorRecorder
     Aggregates the narrow capability protocols for convenience. Implementations
     that only need a subset can implement the individual protocols directly.
 
+    :class:`CheckoutWaitRecorder` is intentionally left out so that implementations
+    written before it keep satisfying this protocol; add ``record_checkout_wait`` to get
+    the checkout wait histogram and the pool timeout counter as well.
+
     Examples:
         >>> class MyMetrics:
         ...     def record_pool_stats(self, pool_size: int, pool_checked_out: int, pool_overflow: int) -> None: ...
         ...     def record_checkout(self, duration: float) -> None: ...
+        ...     def record_checkout_wait(self, duration: float, timed_out: bool = False) -> None: ...
         ...     def record_error(self, error_type: str, is_timeout: bool = False) -> None: ...
         >>> metrics: PostgresMetricsProtocol = MyMetrics()
     """
@@ -71,6 +102,7 @@ class PostgresMetricsProtocol(PoolStatsRecorder, CheckoutRecorder, ErrorRecorder
 
 __all__ = [
     "CheckoutRecorder",
+    "CheckoutWaitRecorder",
     "ErrorRecorder",
     "PoolStatsRecorder",
     "PostgresMetricsProtocol",

{sqlalchemy_foundation_kit-0.3.0 → sqlalchemy_foundation_kit-0.4.0}/sqlalchemy_foundation_kit/session/manager.py

@@ -21,6 +21,7 @@ from sqlalchemy.ext.asyncio import (
 
 from .._typing import SessionT
 from ..base import build_engine_kwargs, resolve_pool_class
+from ..protocols import CheckoutWaitRecorder
 
 if TYPE_CHECKING:
     from sqlalchemy.engine import Connection
@@ -32,6 +33,10 @@ logger = logging.getLogger(__name__)
 
 DEFAULT_DISPOSE_TIMEOUT_SECONDS: float = 30.0
 
+# Set on the pool subclass instrument_pool_class() builds, so attach_metrics() can tell an
+# engine whose pool records the checkout wait from one that silently will not.
+_WAIT_RECORDER_ATTRIBUTE = "_checkout_wait_recorder"
+
 
 def _safe_metric_call(func: Callable[[], None], error_msg: str) -> None:
     """Call a metric-recording function and swallow exceptions.
@@ -49,18 +54,94 @@ def _safe_metric_call(func: Callable[[], None], error_msg: str) -> None:
         logger.exception(error_msg)
 
 
+def instrument_pool_class(pool_class: type, metrics: CheckoutWaitRecorder) -> type:
+    """Build a pool class that times the wait for a connection and counts pool timeouts.
+
+    SQLAlchemy has no event for "a checkout was requested", only for one that succeeded, so
+    the time a caller spends queued for a connection cannot be observed from a listener.
+    The returned subclass wraps :meth:`sqlalchemy.pool.Pool.connect`, which runs exactly
+    once per checkout — for a sync and an async engine alike, since
+    ``Engine.raw_connection()`` goes through it — and through which the pool's
+    ``TimeoutError`` passes exactly once. Under an async pool the queue wait is an
+    ``await_only`` inside that call, so the timer spans the whole suspension and measures
+    the time the caller really waited.
+
+    ``_do_get`` is the wrong hook: ``QueuePool`` recurses into it when the non-blocking get
+    comes back empty and the race for an overflow slot is lost, which is exactly the
+    contended case worth measuring, and the wait would be observed twice.
+
+    The recorder lives on the class, so a pool produced by ``recreate()`` after
+    ``dispose()`` keeps recording.
+
+    Args:
+        pool_class: Pool class to instrument — anything :func:`resolve_pool_class` returns,
+            including a class registered with :func:`register_pool_class`.
+        metrics: Recorder to call once per checkout. A raising recorder is logged and
+            swallowed; the checkout itself is never affected.
+
+    Returns:
+        A subclass of ``pool_class`` suitable for ``create_async_engine(poolclass=...)``.
+
+    Examples:
+        >>> poolclass = instrument_pool_class(resolve_pool_class("async_adapted_queue"), metrics)
+        >>> engine = create_async_engine(url, poolclass=poolclass)
+    """
+
+    class InstrumentedPool(pool_class):  # type: ignore[misc, valid-type]
+        """Pool that reports how long each checkout waited."""
+
+        def connect(self) -> Any:
+            started = time.perf_counter()
+            try:
+                connection = super().connect()
+            except SATimeoutError:
+                _safe_metric_call(
+                    lambda: metrics.record_checkout_wait(
+                        duration=time.perf_counter() - started,
+                        timed_out=True,
+                    ),
+                    "Failed to record database checkout timeout",
+                )
+                raise
+            _safe_metric_call(
+                lambda: metrics.record_checkout_wait(duration=time.perf_counter() - started),
+                "Failed to record database checkout wait",
+            )
+            return connection
+
+    setattr(InstrumentedPool, _WAIT_RECORDER_ATTRIBUTE, metrics)
+    InstrumentedPool.__name__ = f"Instrumented{pool_class.__name__}"
+    InstrumentedPool.__qualname__ = InstrumentedPool.__name__
+    return InstrumentedPool
+
+
 def attach_metrics(engine: AsyncEngine, metrics: PostgresMetricsProtocol) -> None:
     """Attach metrics event listeners to a SQLAlchemy engine.
 
     Registers event handlers for connection checkout, checkin, and error events
     to collect pool statistics and connection metrics.
 
+    The checkout wait and the pool checkout timeout are **not** listeners — no pool event
+    fires for either — and come from the pool class :func:`instrument_pool_class` builds.
+    If ``metrics`` records the wait but the engine's pool was built without it, that is
+    logged as a warning rather than left as a series that never moves.
+
     Args:
         engine: SQLAlchemy ``AsyncEngine`` to attach listeners to.
         metrics: Metrics collector implementing ``PostgresMetricsProtocol``.
     """
     pool = engine.pool
 
+    if isinstance(metrics, CheckoutWaitRecorder) and getattr(type(pool), _WAIT_RECORDER_ATTRIBUTE, None) is None:
+        logger.warning(
+            "%s records the connection checkout wait, but the engine's pool (%s) was not built by "
+            "instrument_pool_class(), so no wait and no pool checkout timeout will ever be recorded. "
+            "Build the engine through AsyncSessionManager, or pass "
+            "instrument_pool_class(pool_class, metrics) as poolclass to create_async_engine().",
+            type(metrics).__name__,
+            type(pool).__name__,
+        )
+
     def record_pool_stats() -> None:
         _safe_metric_call(
             lambda: metrics.record_pool_stats(
@@ -171,7 +252,10 @@ class AsyncSessionManager(Generic[SessionT]):
             isolation_level: Default transaction isolation level (default: None).
             pool_settings: Pool configuration settings (default: None).
             use_orjson: If True, use orjson for JSON serialization (default: False).
-            metrics: Optional metrics collector (default: None).
+            metrics: Optional metrics collector (default: None). One that also implements
+                ``CheckoutWaitRecorder`` gets the pool class wrapped by
+                :func:`instrument_pool_class`, which is what feeds the checkout wait and
+                the pool checkout timeout — neither is reachable from a pool event.
             on_engine_created: Optional callback invoked with ``AsyncEngine`` after creation.
                 Use for OpenTelemetry instrumentation, custom event listeners, etc.
             dispose_timeout: Maximum seconds to wait for engine disposal in :meth:`aclose`
@@ -187,6 +271,10 @@ class AsyncSessionManager(Generic[SessionT]):
         self._close_lock = asyncio.Lock()
         self._dispose_timeout = dispose_timeout
         resolved_poolclass = resolve_pool_class(poolclass)
+        if metrics is not None and isinstance(metrics, CheckoutWaitRecorder):
+            # The wait for a connection is not observable from a pool event, so it has to
+            # be timed inside the pool -- which means deciding the class before the engine.
+            resolved_poolclass = instrument_pool_class(resolved_poolclass, metrics)
         engine_kwargs = build_engine_kwargs(
             echo=echo,
             poolclass=resolved_poolclass,

sqlalchemy_foundation_kit-0.3.0/sqlalchemy_foundation_kit/__version__.py

@@ -1 +0,0 @@
-__version__ = "0.3.0"