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

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

@@ -1,5 +1,19 @@
 # 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)
+
+
+### Features
+
+* stop sending jit and search_path as startup parameters ([#24](https://github.com/bedrock-python/sqlalchemy-foundation-kit/issues/24)) ([704c343](https://github.com/bedrock-python/sqlalchemy-foundation-kit/commit/704c343b932b15f0c6ee434f2fc80ab4732b0f80))
+
 ## [0.2.1](https://github.com/bedrock-python/sqlalchemy-foundation-kit/compare/sqlalchemy-foundation-kit-v0.2.0...sqlalchemy-foundation-kit-v0.2.1) (2026-09-06)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlalchemy-foundation-kit
-Version: 0.2.1
+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/
@@ -295,7 +295,7 @@ Only `sqlalchemy[asyncio]`, `pydantic` and `asyncpg` are required by default —
 ✅ **Single dependency** — All foundation pieces in one place  
 ✅ **Unit of Work pattern** — Transactional consistency with automatic commit/rollback  
 ✅ **Connection pool management** — `AsyncSessionManager` with metrics and health checks  
-✅ **pgbouncer compatible** — Custom connection class for transaction mode  
+✅ **PgBouncer compatible** — A startup packet PgBouncer accepts, `search_path` per transaction, unique statement names  
 ✅ **Observability built-in** — Prometheus metrics + OpenTelemetry tracing  
 ✅ **Type-safe configuration** — Pydantic settings with validation  
 ✅ **Base ORM models** — Pre-configured `Base` with naming conventions and mixins  
@@ -398,7 +398,7 @@ class PostgresConfig:
     application_name: str = "my-service"
     db_schema: str | None = None
     use_orjson_serialization: bool = True
-    jit: str | None = "off"
+    jit: str | None = None
     
     def to_dsn(self) -> str:
         return f"postgresql+asyncpg://{self.connection.user}@{self.connection.host}:{self.connection.port}/{self.connection.database}"
@@ -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.2.1 → sqlalchemy_foundation_kit-0.4.0}/README.md

@@ -44,7 +44,7 @@ Only `sqlalchemy[asyncio]`, `pydantic` and `asyncpg` are required by default —
 ✅ **Single dependency** — All foundation pieces in one place  
 ✅ **Unit of Work pattern** — Transactional consistency with automatic commit/rollback  
 ✅ **Connection pool management** — `AsyncSessionManager` with metrics and health checks  
-✅ **pgbouncer compatible** — Custom connection class for transaction mode  
+✅ **PgBouncer compatible** — A startup packet PgBouncer accepts, `search_path` per transaction, unique statement names  
 ✅ **Observability built-in** — Prometheus metrics + OpenTelemetry tracing  
 ✅ **Type-safe configuration** — Pydantic settings with validation  
 ✅ **Base ORM models** — Pre-configured `Base` with naming conventions and mixins  
@@ -147,7 +147,7 @@ class PostgresConfig:
     application_name: str = "my-service"
     db_schema: str | None = None
     use_orjson_serialization: bool = True
-    jit: str | None = "off"
+    jit: str | None = None
     
     def to_dsn(self) -> str:
         return f"postgresql+asyncpg://{self.connection.user}@{self.connection.host}:{self.connection.port}/{self.connection.database}"
@@ -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.2.1 → 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.2.1"
+    __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.2.1 → sqlalchemy_foundation_kit-0.4.0}/sqlalchemy_foundation_kit/config/postgres.py

@@ -131,9 +131,9 @@ class PostgresSettingsProtocol(Protocol):
         pool: Connection pool settings.
         query: Query execution and transaction settings.
         application_name: Application identifier for connections.
-        db_schema: Optional PostgreSQL schema name.
+        db_schema: Optional PostgreSQL ``search_path``, applied to every transaction.
         use_orjson_serialization: Enable orjson for JSON operations.
-        jit: JIT compilation setting (PgBouncer compatibility).
+        jit: JIT compilation setting, sent as a startup parameter only when not ``None``.
 
     Examples:
         Implementing the protocol:
@@ -144,7 +144,7 @@ class PostgresSettingsProtocol(Protocol):
             ...     application_name: str = "my-app"
             ...     db_schema: str | None = None
             ...     use_orjson_serialization: bool = True
-            ...     jit: str | None = "off"
+            ...     jit: str | None = None
             ...
             ...     def to_dsn(self) -> str:
             ...         return f"postgresql://{self.connection.user}@{self.connection.host}..."

{sqlalchemy_foundation_kit-0.2.1 → 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.2.1 → sqlalchemy_foundation_kit-0.4.0}/sqlalchemy_foundation_kit/contrib/settings/postgres.py

@@ -98,9 +98,12 @@ class BasePostgresConfig(BaseSettings):
         pool: Connection pool configuration (size, overflow, timeouts).
         query: Query execution settings (echo, caching, isolation level).
         application_name: Application name for connection identification.
-        db_schema: Optional PostgreSQL schema name.
+        db_schema: Optional PostgreSQL ``search_path`` — a schema, or a comma-separated
+            list — applied to every transaction with ``SET LOCAL`` semantics.
         use_orjson_serialization: Use orjson for JSON serialization (requires orjson).
-        jit: JIT compilation setting (off/on) for PgBouncer compatibility.
+        jit: JIT compilation setting (off/on), sent as a startup parameter only when set.
+            ``None`` (the default) sends nothing and leaves the server's own setting; a
+            transaction-mode PgBouncer rejects the parameter unless it tracks it.
         metrics_enabled: Enable connection pool metrics collection.
 
     Examples:
@@ -125,12 +128,18 @@ class BasePostgresConfig(BaseSettings):
 
     # Top-level settings
     application_name: str = Field(description="Application name for PostgreSQL")
-    db_schema: str | None = Field(default=None, description="PostgreSQL schema name")
+    db_schema: str | None = Field(
+        default=None,
+        description="PostgreSQL search_path (a schema or a comma-separated list), applied to every transaction",
+    )
     use_orjson_serialization: bool = Field(
         default=True,
         description="Use orjson for JSON serialization (requires orjson installed)",
     )
-    jit: PostgresJit | None = Field(default="off", description="JIT setting (off/on)")
+    jit: PostgresJit | None = Field(
+        default=None,
+        description="JIT setting (off/on), sent as a startup parameter only when set",
+    )
     metrics_enabled: bool = Field(default=False, description="Enable PostgreSQL metrics")
 
     def __repr__(self) -> str:

{sqlalchemy_foundation_kit-0.2.1 → 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.2.1 → 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.2.1 → sqlalchemy_foundation_kit-0.4.0}/sqlalchemy_foundation_kit/session/builder.py

@@ -77,6 +77,7 @@ class AsyncSessionManagerBuilder(Generic[SessionT]):
         self._metrics: PostgresMetricsProtocol | None = None
         self._on_engine_created: Callable[[AsyncEngine], None] | None = None
         self._dispose_timeout: float | None = None
+        self._search_path: str | None = None
         self._extra_kwargs: dict[str, object] = {}
 
     def with_echo(self, echo: bool = True) -> AsyncSessionManagerBuilder[SessionT]:
@@ -258,6 +259,22 @@ class AsyncSessionManagerBuilder(Generic[SessionT]):
         self._dispose_timeout = timeout
         return self
 
+    def with_search_path(self, search_path: str) -> AsyncSessionManagerBuilder[SessionT]:
+        """Apply a PostgreSQL ``search_path`` to every transaction.
+
+        Issued with ``SET LOCAL`` semantics at the start of each transaction — the one
+        scope a transaction-mode pooler such as PgBouncer honours. See
+        :func:`~sqlalchemy_foundation_kit.session.manager.attach_search_path`.
+
+        Args:
+            search_path: A schema, or a comma-separated list such as ``"tenant_7, public"``.
+
+        Returns:
+            Self for method chaining.
+        """
+        self._search_path = search_path
+        return self
+
     def build(self) -> AsyncSessionManager[SessionT]:
         """Build AsyncSessionManager instance with configured parameters.
 
@@ -284,6 +301,7 @@ class AsyncSessionManagerBuilder(Generic[SessionT]):
             "use_orjson": self._use_orjson,
             "metrics": self._metrics,
             "on_engine_created": self._on_engine_created,
+            "search_path": self._search_path,
         }
         if self._dispose_timeout is not None:
             kwargs["dispose_timeout"] = self._dispose_timeout

{sqlalchemy_foundation_kit-0.2.1 → sqlalchemy_foundation_kit-0.4.0}/sqlalchemy_foundation_kit/session/factories.py

@@ -31,6 +31,13 @@ def create_async_session_manager(
 ) -> AsyncSessionManager[AsyncSession]:
     """Create async session manager with PostgreSQL-specific configuration.
 
+    The startup packet carries ``application_name`` and, only when the config sets it,
+    ``jit``; nothing else, because a transaction-mode pooler such as PgBouncer rejects
+    startup parameters it does not track (``unsupported startup parameter: jit``) or,
+    with ``ignore_startup_parameters``, silently drops them. ``db_schema`` therefore
+    travels as the manager's ``search_path`` and is applied with ``SET LOCAL`` semantics
+    at the start of every transaction, which is the one scope such a pooler honours.
+
     Args:
         postgres_config: PostgreSQL configuration implementing PostgresSettingsProtocol.
         application_name: Optional custom application name. If None, uses postgres_config.application_name.
@@ -41,7 +48,8 @@ def create_async_session_manager(
             which provides pgbouncer transaction-mode compatibility.
         extra_server_settings: Additional PostgreSQL ``server_settings`` to merge with defaults
             (e.g., ``{"statement_timeout": "30000", "timezone": "UTC"}``). User-provided keys
-            override library defaults.
+            override library defaults. These are startup parameters: through PgBouncer only
+            the ones it tracks arrive (``track_extra_parameters``).
         extra_connect_args: Additional asyncpg ``connect_args`` to merge with defaults
             (e.g., ``{"command_timeout": 60}``). User-provided keys override library defaults.
         **kwargs: Additional keyword arguments passed to AsyncSessionManager.
@@ -73,11 +81,11 @@ def create_async_session_manager(
     """
     app_name = application_name or postgres_config.application_name
 
-    # Build server settings with optional overrides
+    # Build server settings with optional overrides. These are startup parameters, so
+    # search_path is deliberately not among them -- see the docstring.
     server_settings: dict[str, str] = {
         "application_name": app_name,
         **({"jit": postgres_config.jit} if postgres_config.jit is not None else {}),
-        **({"search_path": postgres_config.db_schema} if postgres_config.db_schema is not None else {}),
         **(extra_server_settings or {}),
     }
 
@@ -100,5 +108,6 @@ def create_async_session_manager(
         use_orjson=postgres_config.use_orjson_serialization,
         metrics=metrics,
         on_engine_created=on_engine_created,
+        search_path=postgres_config.db_schema,
         **kwargs,
     )

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

@@ -10,7 +10,7 @@ from contextlib import asynccontextmanager
 from types import TracebackType
 from typing import TYPE_CHECKING, Any, Generic, cast
 
-from sqlalchemy import event
+from sqlalchemy import event, text
 from sqlalchemy.exc import TimeoutError as SATimeoutError
 from sqlalchemy.ext.asyncio import (
     AsyncEngine,
@@ -21,8 +21,11 @@ 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
+
     from ..config import PoolSettingsProtocol
     from ..protocols import PostgresMetricsProtocol
 
@@ -30,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.
@@ -47,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(
@@ -100,6 +183,35 @@ def attach_metrics(engine: AsyncEngine, metrics: PostgresMetricsProtocol) -> Non
     event.listen(engine.sync_engine, "handle_error", on_error)
 
 
+def attach_search_path(engine: AsyncEngine, search_path: str) -> None:
+    """Apply ``search_path`` to every transaction the engine begins.
+
+    Registers a ``begin`` listener that issues ``set_config('search_path', …, true)`` —
+    the function form of ``SET LOCAL``, with the value as a bind parameter — as the first
+    statement of each transaction, so the setting lives exactly as long as the transaction
+    does. That is the one scope a transaction-mode pooler such as PgBouncer honours: a
+    startup parameter is rejected or dropped before it reaches PostgreSQL, and a plain
+    ``SET`` on a server connection leaks to whichever client is handed it next.
+
+    Under the asyncpg adapter ``BEGIN`` is sent lazily with the first statement, so the
+    ``set_config`` call lands inside the transaction rather than ahead of it. Every
+    transaction is covered — a session's autobegin, ``session.begin()``, a raw
+    ``engine.connect()``, the one that follows a ``commit()`` — but a statement run with
+    ``isolation_level="AUTOCOMMIT"`` begins none and runs with the server's default.
+
+    Args:
+        engine: SQLAlchemy ``AsyncEngine`` to attach the listener to.
+        search_path: Value for ``search_path`` — a schema, or a comma-separated list such
+            as ``"tenant_7, public"``.
+    """
+    statement = text("SELECT set_config('search_path', :search_path, true)")
+
+    def on_begin(conn: Connection) -> None:
+        conn.execute(statement, {"search_path": search_path})
+
+    event.listen(engine.sync_engine, "begin", on_begin)
+
+
 class AsyncSessionManager(Generic[SessionT]):
     """Manages async database sessions with configurable connection pooling.
 
@@ -124,6 +236,7 @@ class AsyncSessionManager(Generic[SessionT]):
         metrics: PostgresMetricsProtocol | None = None,
         on_engine_created: Callable[[AsyncEngine], None] | None = None,
         dispose_timeout: float = DEFAULT_DISPOSE_TIMEOUT_SECONDS,
+        search_path: str | None = None,
         **kwargs: object,
     ) -> None:
         """Initialize session manager with direct configuration.
@@ -139,18 +252,29 @@ 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`
                 (default: 30.0). Lower this in tests or short-lived environments; raise it
                 if you have long-running transactions that need more time to settle.
+            search_path: PostgreSQL ``search_path`` applied to every transaction with
+                ``SET LOCAL`` semantics, which is what survives a transaction-mode pooler
+                (default: None — nothing is sent, the server default applies). See
+                :func:`attach_search_path`.
             **kwargs: Additional keyword arguments for ``create_async_engine``.
         """
         self._closed = False
         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,
@@ -174,6 +298,9 @@ class AsyncSessionManager(Generic[SessionT]):
         if metrics:
             attach_metrics(self._engine, metrics)
 
+        if search_path is not None:
+            attach_search_path(self._engine, search_path)
+
         if on_engine_created is not None:
             on_engine_created(self._engine)
 

sqlalchemy_foundation_kit-0.2.1/sqlalchemy_foundation_kit/__version__.py

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