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

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

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.5.0](https://github.com/bedrock-python/sqlalchemy-foundation-kit/compare/sqlalchemy-foundation-kit-v0.4.0...sqlalchemy-foundation-kit-v0.5.0) (2026-10-16)
+
+
+### ⚠ BREAKING CHANGES
+
+* BasePostgresConfig.use_orjson_serialization now defaults to False, matching AsyncSessionManager and the builder. A service that has orjson installed, kept the default, and writes values only orjson serializes (datetime, UUID, Decimal, non-str keys) into JSON columns now gets StatementError (TypeError: Object of type datetime is not JSON serializable). Set use_orjson_serialization=True to keep the old behaviour.
+* uow.query() now opens its transaction READ ONLY. A write inside it (INSERT, UPDATE, DELETE, DDL, nextval()) fails with SQLSTATE 25006 instead of being rolled back silently, or persisted when followed by an explicit session.commit(). Move writes to uow.transaction().
+
+### Bug Fixes
+
+* build null and static pools from PoolSettings, and stop recommending the sync queue pool ([#61](https://github.com/bedrock-python/sqlalchemy-foundation-kit/issues/61)) ([608d327](https://github.com/bedrock-python/sqlalchemy-foundation-kit/commit/608d32747361321895f6fc43f5e77da6937375ff))
+* count connect timeouts, not statement timeouts, in connection_timeouts_total ([#63](https://github.com/bedrock-python/sqlalchemy-foundation-kit/issues/63)) ([961e0e8](https://github.com/bedrock-python/sqlalchemy-foundation-kit/commit/961e0e862cb540525cda99b5ecc79ee12cbab2e4))
+* default use_orjson_serialization to False, so the [settings] quick start runs ([#66](https://github.com/bedrock-python/sqlalchemy-foundation-kit/issues/66)) ([3addfdd](https://github.com/bedrock-python/sqlalchemy-foundation-kit/commit/3addfdd50c98657966867b680121facd596b6810))
+* read the pool gauges when they are scraped, and never export a negative overflow ([#62](https://github.com/bedrock-python/sqlalchemy-foundation-kit/issues/62)) ([e85ac96](https://github.com/bedrock-python/sqlalchemy-foundation-kit/commit/e85ac96bd875ee47729f029c8046ea85be48f712))
+* run query() in a READ ONLY transaction, as documented ([#64](https://github.com/bedrock-python/sqlalchemy-foundation-kit/issues/64)) ([cb77404](https://github.com/bedrock-python/sqlalchemy-foundation-kit/commit/cb7740468cc86d1d7e9f7bda80d56b27b0300739))
+* stop logging a failed flush's parameters and row values ([#65](https://github.com/bedrock-python/sqlalchemy-foundation-kit/issues/65)) ([6dd88ba](https://github.com/bedrock-python/sqlalchemy-foundation-kit/commit/6dd88ba34de6f6fa3306f7e9002788ab57f7797c))
+
 ## [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)
 
 
@@ -51,10 +68,3 @@
 ### Documentation
 
 * **foundation-kit:** add comprehensive documentation for all features ([8d10f84](https://github.com/bedrock-python/sqlalchemy-foundation-kit/commit/8d10f84179273a8cc40dc1fe326bddab84379d32))
-
-## Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlalchemy-foundation-kit
-Version: 0.4.0
+Version: 0.5.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/
@@ -216,6 +216,8 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
@@ -397,7 +399,7 @@ class PostgresConfig:
     query: QuerySettingsProtocol = MyQuerySettings()
     application_name: str = "my-service"
     db_schema: str | None = None
-    use_orjson_serialization: bool = True
+    use_orjson_serialization: bool = False
     jit: str | None = None
     
     def to_dsn(self) -> str:

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

@@ -146,7 +146,7 @@ class PostgresConfig:
     query: QuerySettingsProtocol = MyQuerySettings()
     application_name: str = "my-service"
     db_schema: str | None = None
-    use_orjson_serialization: bool = True
+    use_orjson_serialization: bool = False
     jit: str | None = None
     
     def to_dsn(self) -> str:

{sqlalchemy_foundation_kit-0.4.0 → sqlalchemy_foundation_kit-0.5.0}/pyproject.toml

@@ -25,6 +25,8 @@ classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Typing :: Typed",
 ]

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

@@ -33,6 +33,7 @@ from .protocols import (
     CheckoutRecorder,
     CheckoutWaitRecorder,
     ErrorRecorder,
+    PoolStatsFunctionRecorder,
     PoolStatsRecorder,
     PostgresMetricsProtocol,
 )
@@ -65,7 +66,7 @@ from .uow import (
 try:
     __version__ = version("sqlalchemy-foundation-kit")
 except PackageNotFoundError:  # pragma: no cover
-    __version__ = "0.4.0"
+    __version__ = "0.5.0"
 
 __all__ = [  # noqa: RUF022
     # Base ORM
@@ -92,6 +93,7 @@ __all__ = [  # noqa: RUF022
     "CheckoutRecorder",
     "CheckoutWaitRecorder",
     "ErrorRecorder",
+    "PoolStatsFunctionRecorder",
     "PoolStatsRecorder",
     "PostgresMetricsProtocol",
     # Session Management

sqlalchemy_foundation_kit-0.5.0/sqlalchemy_foundation_kit/__version__.py

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

{sqlalchemy_foundation_kit-0.4.0 → sqlalchemy_foundation_kit-0.5.0}/sqlalchemy_foundation_kit/base/engine.py

@@ -224,26 +224,25 @@ def _apply_pool_settings(
     Maps pool settings to SQLAlchemy's expected ``pool_*`` keyword arguments.
     Note: pool_pre_ping is already set in build_engine_kwargs, so not applied here.
 
-    Only applies pool size/overflow/recycle/timeout for pool classes that support them.
-    Checks if the pool class accepts these parameters via hasattr to avoid passing
-    unsupported kwargs to pools like NullPool or StaticPool.
+    ``pool_recycle`` applies to every pool class. ``pool_size``, ``max_overflow`` and
+    ``pool_timeout`` describe a queue of connections and exist only on ``QueuePool``
+    and its subclasses -- the async queue pools, a registered subclass, the class
+    ``instrument_pool_class`` builds. ``create_async_engine`` rejects them for any other
+    pool (``NullPool``, ``StaticPool``), so they are left out there.
 
     Args:
         engine_kwargs: Dictionary to update with pool configuration.
         poolclass: Pool class being configured.
         pool_settings: Pool configuration settings.
     """
-    # Build pool parameters dict
-    params = {
-        "pool_size": pool_settings.size,
-        "max_overflow": pool_settings.max_overflow,
-        "pool_recycle": pool_settings.recycle,
-        "pool_timeout": pool_settings.timeout,
-    }
+    params: dict[str, object] = {"pool_recycle": pool_settings.recycle}
+    if issubclass(poolclass, QueuePool):
+        params.update(
+            pool_size=pool_settings.size,
+            max_overflow=pool_settings.max_overflow,
+            pool_timeout=pool_settings.timeout,
+        )
 
-    # Apply only non-None parameters
-    # SQLAlchemy pool classes that don't support these params will ignore them
-    # or raise TypeError if passed, so we rely on the pool class itself to validate
     engine_kwargs.update({k: v for k, v in params.items() if v is not None})
 
 

{sqlalchemy_foundation_kit-0.4.0 → sqlalchemy_foundation_kit-0.5.0}/sqlalchemy_foundation_kit/config/postgres.py

@@ -143,7 +143,7 @@ class PostgresSettingsProtocol(Protocol):
             ...     query: QuerySettingsProtocol
             ...     application_name: str = "my-app"
             ...     db_schema: str | None = None
-            ...     use_orjson_serialization: bool = True
+            ...     use_orjson_serialization: bool = False
             ...     jit: str | None = None
             ...
             ...     def to_dsn(self) -> str:

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

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import re
+from collections.abc import Callable
 
 try:
     from prometheus_client import Counter, Gauge, Histogram
@@ -59,19 +60,24 @@ class PostgresMetrics:
     """Postgres connection pool metrics.
 
     Metrics:
-        - postgres_db_pool_size: Current database connection pool size.
+        - postgres_db_pool_size: Configured pool_size of the connection pool.
         - 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_pool_overflow: Number of open connections over pool_size (within max_overflow).
         - 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_timeouts_total: Number of times acquiring a connection timed out:
+          pool checkout timeouts and connect timeouts. Statement timeouts are not counted here.
         - postgres_db_connection_errors_total: Number of connection errors.
 
     Labels:
         - error_type: Type of connection error (for errors_total).
 
+    The three pool gauges are read from the pool when the registry is collected, not
+    sampled from pool events, so an idle pool reports what it holds. One instance reports
+    one engine: attached to a second engine, the gauges follow the second.
+
     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``).
@@ -90,7 +96,7 @@ class PostgresMetrics:
 
         self.pool_size = Gauge(
             _make_metric_name("postgres_db_pool_size", prefix),
-            "Current database connection pool size",
+            "Configured pool_size of the database connection pool",
         )
         self.pool_checked_out = Gauge(
             _make_metric_name("postgres_db_pool_checked_out", prefix),
@@ -98,7 +104,7 @@ class PostgresMetrics:
         )
         self.pool_overflow = Gauge(
             _make_metric_name("postgres_db_pool_overflow", prefix),
-            "Number of connections over pool_size (within max_overflow)",
+            "Number of open connections over pool_size (within max_overflow)",
         )
         self.connection_checkout_wait = Histogram(
             _make_metric_name("postgres_db_connection_checkout_wait_seconds", prefix),
@@ -117,7 +123,7 @@ class PostgresMetrics:
         )
         self.connection_timeouts_total = Counter(
             _make_metric_name("postgres_db_connection_timeouts_total", prefix),
-            "Number of connection checkout timeouts",
+            "Number of times acquiring a connection timed out: pool checkout timeouts and connect timeouts",
         )
         self.connection_errors_total = Counter(
             _make_metric_name("postgres_db_connection_errors_total", prefix),
@@ -136,6 +142,17 @@ class PostgresMetrics:
         self.pool_checked_out.set(float(pool_checked_out))
         self.pool_overflow.set(float(pool_overflow))
 
+    def set_pool_stats_functions(
+        self,
+        pool_size: Callable[[], float],
+        pool_checked_out: Callable[[], float],
+        pool_overflow: Callable[[], float],
+    ) -> None:
+        """Read the pool gauges from these functions whenever the registry is collected."""
+        self.pool_size.set_function(pool_size)
+        self.pool_checked_out.set_function(pool_checked_out)
+        self.pool_overflow.set_function(pool_overflow)
+
     def record_checkout(
         self,
         duration: float,
@@ -154,10 +171,10 @@ class PostgresMetrics:
         duration: float,
         timed_out: bool = False,
     ) -> None:
-        """Record the wait for a connection from the pool, and count a pool timeout.
+        """Record the wait for a connection from the pool, and count a timeout acquiring it.
 
-        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.
+        A pool checkout timeout and a connect timeout never reach the engine's
+        ``handle_error`` listener; this is the only place either is counted.
         """
         self.connection_checkout_wait.observe(duration)
         if timed_out:
@@ -168,7 +185,11 @@ class PostgresMetrics:
         error_type: str,
         is_timeout: bool = False,
     ) -> None:
-        """Record a database connection or execution error."""
+        """Record a database connection or execution error.
+
+        ``is_timeout`` is kept for compatibility and still counts a timeout when a custom
+        caller sets it; the library itself no longer does.
+        """
         self.connection_errors_total.labels(error_type=error_type).inc()
         if is_timeout:
             self.connection_timeouts_total.inc()

{sqlalchemy_foundation_kit-0.4.0 → sqlalchemy_foundation_kit-0.5.0}/sqlalchemy_foundation_kit/contrib/settings/postgres.py

@@ -47,8 +47,15 @@ class PoolSettings(BaseModel):
 
     Groups all connection pool-related parameters for SQLAlchemy engine.
 
+    ``size``, ``max_overflow`` and ``timeout`` apply to the queue pools
+    (``async_adapted_queue``, ``fallback_async_adapted_queue``) and are not passed to any
+    other pool. ``static`` is SQLAlchemy's ``StaticPool``: one connection shared by every
+    session, which concurrent sessions cannot use safely -- for tests, never as a
+    fixed-size pool. A fixed-size pool is ``async_adapted_queue`` with ``max_overflow=0``.
+
     Examples:
         >>> pool = PoolSettings(size=10, max_overflow=20)
+        >>> fixed = PoolSettings(size=10, max_overflow=0)
     """
 
     kind: PoolClassStr = Field(
@@ -68,8 +75,11 @@ class PoolSettings(BaseModel):
     @model_validator(mode="after")
     def _validate_pool_settings(self) -> PoolSettings:
         """Validate pool configuration constraints."""
-        if self.kind == "static" and self.max_overflow > 0:
-            raise ValueError(f"max_overflow must be 0 for static pool, got {self.max_overflow}")
+        if self.kind == "static" and self.size > 1:
+            raise ValueError(
+                f"size must be 1 for a static pool, got {self.size}: a static pool is one connection "
+                "shared by every session. For a fixed-size pool use kind='async_adapted_queue' with max_overflow=0"
+            )
         return self
 
 
@@ -100,7 +110,9 @@ class BasePostgresConfig(BaseSettings):
         application_name: Application name for connection identification.
         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).
+        use_orjson_serialization: Serialize JSON / JSONB columns with orjson. Off by default:
+            it needs the ``orjson`` extra, and orjson serializes some values (``datetime``,
+            ``UUID``, ``Decimal``, non-``str`` keys) that ``json.dumps`` rejects.
         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.
@@ -133,8 +145,8 @@ class BasePostgresConfig(BaseSettings):
         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)",
+        default=False,
+        description="Use orjson for JSON serialization (requires the orjson extra)",
     )
     jit: PostgresJit | None = Field(
         default=None,

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

@@ -10,6 +10,7 @@ from .metrics import (
     CheckoutRecorder,
     CheckoutWaitRecorder,
     ErrorRecorder,
+    PoolStatsFunctionRecorder,
     PoolStatsRecorder,
     PostgresMetricsProtocol,
 )
@@ -18,6 +19,7 @@ __all__ = [
     "CheckoutRecorder",
     "CheckoutWaitRecorder",
     "ErrorRecorder",
+    "PoolStatsFunctionRecorder",
     "PoolStatsRecorder",
     "PostgresMetricsProtocol",
 ]

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

@@ -7,6 +7,7 @@ the narrow protocols selectively (e.g., only record errors), and
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from typing import Protocol, runtime_checkable
 
 
@@ -21,10 +22,51 @@ class PoolStatsRecorder(Protocol):
     ) -> None:
         """Record database connection pool statistics.
 
+        Called from the pool's ``checkout`` and ``checkin`` events, so each call describes
+        the pool as that event saw it -- and ``checkin`` fires before the connection is
+        back, so the last call of a burst still counts it as checked out. A recorder that
+        also implements :class:`PoolStatsFunctionRecorder` reads the pool when it is
+        collected instead, and this method is then not called.
+
         Args:
-            pool_size: Current total number of connections in the pool.
+            pool_size: The configured ``pool_size`` of a queue pool, 0 for any other pool.
             pool_checked_out: Number of connections currently in use.
-            pool_overflow: Number of connections over the configured pool_size.
+            pool_overflow: Number of open connections over ``pool_size``, within
+                ``max_overflow``; never negative.
+        """
+        ...
+
+
+@runtime_checkable
+class PoolStatsFunctionRecorder(Protocol):
+    """Capability protocol for reading pool statistics when the metrics are collected.
+
+    A gauge sampled from pool events goes stale: the ``checkin`` event fires before the
+    connection is returned, and nothing fires once the pool is idle, so an idle pool keeps
+    reporting the last burst. A recorder that implements this protocol is handed
+    functions that read the pool on demand -- ``prometheus_client``'s
+    ``Gauge.set_function`` -- and :class:`PoolStatsRecorder` is then not used for it.
+
+    Not part of :class:`PostgresMetricsProtocol`, so implementations written without it
+    stay valid; the session manager tests for it with ``isinstance``.
+    """
+
+    def set_pool_stats_functions(
+        self,
+        pool_size: Callable[[], float],
+        pool_checked_out: Callable[[], float],
+        pool_overflow: Callable[[], float],
+    ) -> None:
+        """Read the pool statistics from these functions whenever they are collected.
+
+        Each function reads the engine's current pool, so the pool that ``dispose()``
+        creates is the one reported. Values mean the same as in
+        :meth:`PoolStatsRecorder.record_pool_stats`.
+
+        Args:
+            pool_size: Returns the configured ``pool_size``.
+            pool_checked_out: Returns the number of connections currently in use.
+            pool_overflow: Returns the number of open connections over ``pool_size``.
         """
         ...
 
@@ -60,22 +102,32 @@ class CheckoutWaitRecorder(Protocol):
         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``.
+            timed_out: True if the wait ended in a timeout rather than in a connection:
+                the pool checkout timeout (``sqlalchemy.exc.TimeoutError``) or the
+                driver's connect timeout (a builtin ``TimeoutError`` while the pool opens
+                a connection). Neither reaches the engine's ``handle_error``.
         """
         ...
 
 
+@runtime_checkable
 class ErrorRecorder(Protocol):
-    """Capability protocol for recording database errors."""
+    """Capability protocol for recording database errors.
+
+    Called for every error the engine's ``handle_error`` sees -- errors on an established
+    connection, a statement timeout among them -- and, from the instrumented pool, for a
+    connection the pool could not open. ``runtime_checkable`` so the instrumented pool can
+    tell whether its recorder takes errors too.
+    """
 
     def record_error(self, error_type: str, is_timeout: bool = False) -> None:
         """Record a database connection or execution error.
 
         Args:
             error_type: The type of error that occurred (e.g., "OperationalError").
-            is_timeout: True if this error was specifically a connection checkout timeout.
+            is_timeout: Kept for compatibility; the library no longer sets it. Timeouts
+                acquiring a connection are reported through
+                :meth:`CheckoutWaitRecorder.record_checkout_wait`.
         """
         ...
 
@@ -104,6 +156,7 @@ __all__ = [
     "CheckoutRecorder",
     "CheckoutWaitRecorder",
     "ErrorRecorder",
+    "PoolStatsFunctionRecorder",
     "PoolStatsRecorder",
     "PostgresMetricsProtocol",
 ]

{sqlalchemy_foundation_kit-0.4.0 → sqlalchemy_foundation_kit-0.5.0}/sqlalchemy_foundation_kit/session/builder.py

@@ -32,7 +32,7 @@ class AsyncSessionManagerBuilder(Generic[SessionT]):
         Basic usage:
             >>> manager = (
             ...     AsyncSessionManagerBuilder("postgresql+asyncpg://...")
-            ...     .with_pool("queue")
+            ...     .with_pool("async_adapted_queue")
             ...     .with_echo(True)
             ...     .build()
             ... )
@@ -41,7 +41,7 @@ class AsyncSessionManagerBuilder(Generic[SessionT]):
             >>> manager = (
             ...     AsyncSessionManagerBuilder[CustomSession]("postgresql+asyncpg://...")
             ...     .with_session_class(CustomSession)
-            ...     .with_pool("queue", pool_settings=settings.pool)
+            ...     .with_pool("async_adapted_queue", pool_settings=settings.pool)
             ...     .with_metrics(metrics)
             ...     .with_callbacks(on_engine_created=instrument_engine)
             ...     .with_json_serialization(orjson=True)
@@ -52,7 +52,7 @@ class AsyncSessionManagerBuilder(Generic[SessionT]):
         Reusable configuration:
             >>> builder = (
             ...     AsyncSessionManagerBuilder("postgresql+asyncpg://...")
-            ...     .with_pool("queue")
+            ...     .with_pool("async_adapted_queue")
             ...     .with_metrics(metrics)
             ... )
             >>> manager1 = builder.with_echo(True).build()
@@ -100,8 +100,10 @@ class AsyncSessionManagerBuilder(Generic[SessionT]):
         """Configure connection pool.
 
         Args:
-            poolclass: Pool class name or type (e.g., "queue", "null").
-            pool_settings: Optional pool configuration settings.
+            poolclass: Pool class name or type: ``"async_adapted_queue"`` for a service,
+                ``"null"`` (the default when this is not called) for tests and scripts.
+            pool_settings: Optional pool configuration settings. ``size``,
+                ``max_overflow`` and ``timeout`` apply to the queue pools only.
 
         Returns:
             Self for method chaining.

sqlalchemy_foundation_kit-0.5.0/sqlalchemy_foundation_kit/session/connection.py

@@ -0,0 +1,40 @@
+"""asyncpg connection class with uuid prepared-statement names."""
+
+import uuid
+
+import asyncpg
+
+
+class AsyncCConnection(asyncpg.Connection):
+    """asyncpg connection whose prepared statements are named with a uuid.
+
+    Overrides only the private ``_get_unique_id``, so statement names are unique across
+    every connection rather than counted per connection. The only failure that prevents
+    is two clients colliding on a name on a shared server connection
+    (https://github.com/sqlalchemy/sqlalchemy/issues/6467). That needs a transaction-mode
+    PgBouncer that does not track prepared statements, where a named statement fails
+    anyway with ``prepared statement ... does not exist``.
+
+    It is not what makes the library work behind PgBouncer. With
+    ``statement_cache_size=0`` (the default) asyncpg sends unnamed statements and asks for
+    no name at all; with ``statement_cache_size > 0`` PgBouncer has to track prepared
+    statements itself (1.21+ with ``max_prepared_statements > 0``, the default from 1.24),
+    and then rewrites the names per server connection. Kept as the default connection
+    class of :func:`create_async_session_manager` because it is harmless.
+    """
+
+    def _get_unique_id(self, prefix: str) -> str:
+        """Generate unique ID for prepared statements.
+
+        Args:
+            prefix: Prefix for the unique ID.
+
+        Returns:
+            A unique string ID including the prefix and a UUID.
+        """
+        return f"__asyncpg_{prefix}_{uuid.uuid4()}__"
+
+
+__all__ = [
+    "AsyncCConnection",
+]

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

@@ -44,8 +44,11 @@ def create_async_session_manager(
         metrics: Optional metrics collector for connection pool monitoring.
         on_engine_created: Optional callback invoked with the AsyncEngine right after creation.
             Use it to attach OpenTelemetry instrumentation, custom listeners, etc.
-        connection_class: Custom asyncpg Connection subclass. Defaults to ``AsyncCConnection``
-            which provides pgbouncer transaction-mode compatibility.
+        connection_class: Custom asyncpg Connection subclass. Defaults to ``AsyncCConnection``,
+            which names statements with a uuid. PgBouncer compatibility does not depend on
+            it: with ``statement_cache_size=0`` (the default) asyncpg sends unnamed
+            statements that any PgBouncer carries, and ``statement_cache_size > 0`` needs
+            PgBouncer 1.21+ with ``max_prepared_statements > 0`` whatever the class.
         extra_server_settings: Additional PostgreSQL ``server_settings`` to merge with defaults
             (e.g., ``{"statement_timeout": "30000", "timezone": "UTC"}``). User-provided keys
             override library defaults. These are startup parameters: through PgBouncer only

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

@@ -21,10 +21,11 @@ from sqlalchemy.ext.asyncio import (
 
 from .._typing import SessionT
 from ..base import build_engine_kwargs, resolve_pool_class
-from ..protocols import CheckoutWaitRecorder
+from ..protocols import CheckoutWaitRecorder, ErrorRecorder, PoolStatsFunctionRecorder
 
 if TYPE_CHECKING:
     from sqlalchemy.engine import Connection
+    from sqlalchemy.pool import Pool
 
     from ..config import PoolSettingsProtocol
     from ..protocols import PostgresMetricsProtocol
@@ -54,8 +55,27 @@ def _safe_metric_call(func: Callable[[], None], error_msg: str) -> None:
         logger.exception(error_msg)
 
 
+def _pool_size(pool: Pool) -> int:
+    """The configured ``pool_size`` of a queue pool, 0 for a pool without one."""
+    return int(pool.size()) if hasattr(pool, "size") else 0
+
+
+def _pool_checked_out(pool: Pool) -> int:
+    """Connections currently in use."""
+    return int(pool.checkedout()) if hasattr(pool, "checkedout") else 0
+
+
+def _pool_overflow(pool: Pool) -> int:
+    """Open connections over ``pool_size``.
+
+    ``QueuePool.overflow()`` starts at ``-pool_size`` and counts every connection the pool
+    opens, so it is negative until the pool has grown past ``pool_size``.
+    """
+    return max(int(pool.overflow()), 0) if hasattr(pool, "overflow") else 0
+
+
 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.
+    """Build a pool class that times the wait for a connection and counts timeouts acquiring one.
 
     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.
@@ -66,6 +86,15 @@ def instrument_pool_class(pool_class: type, metrics: CheckoutWaitRecorder) -> ty
     ``await_only`` inside that call, so the timer spans the whole suspension and measures
     the time the caller really waited.
 
+    Every checkout records its wait, however it ends. Two endings count as a timeout: the
+    pool's own ``sqlalchemy.exc.TimeoutError`` (the queue outlasted ``pool_timeout``) and
+    a builtin ``TimeoutError`` from the driver while the pool opens a new connection
+    (asyncpg's connect ``timeout``). Any other exception is a connection the pool could
+    not open, and is also recorded as an error when ``metrics`` implements
+    ``ErrorRecorder`` -- unless it is the driver's DBAPI error, which the engine's
+    ``handle_error`` reports itself. asyncpg's connect errors are not: none of them reaches
+    ``handle_error``, so this is the only place a database refusing connections shows up.
+
     ``_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.
@@ -86,6 +115,7 @@ def instrument_pool_class(pool_class: type, metrics: CheckoutWaitRecorder) -> ty
         >>> poolclass = instrument_pool_class(resolve_pool_class("async_adapted_queue"), metrics)
         >>> engine = create_async_engine(url, poolclass=poolclass)
     """
+    error_recorder = metrics if isinstance(metrics, ErrorRecorder) else None
 
     class InstrumentedPool(pool_class):  # type: ignore[misc, valid-type]
         """Pool that reports how long each checkout waited."""
@@ -94,7 +124,7 @@ def instrument_pool_class(pool_class: type, metrics: CheckoutWaitRecorder) -> ty
             started = time.perf_counter()
             try:
                 connection = super().connect()
-            except SATimeoutError:
+            except (SATimeoutError, TimeoutError):
                 _safe_metric_call(
                     lambda: metrics.record_checkout_wait(
                         duration=time.perf_counter() - started,
@@ -103,12 +133,29 @@ def instrument_pool_class(pool_class: type, metrics: CheckoutWaitRecorder) -> ty
                     "Failed to record database checkout timeout",
                 )
                 raise
+            except Exception as exc:
+                _safe_metric_call(
+                    lambda: metrics.record_checkout_wait(duration=time.perf_counter() - started),
+                    "Failed to record database checkout wait",
+                )
+                if error_recorder is not None and not self._reported_by_handle_error(exc):
+                    error_type = type(exc).__name__
+                    _safe_metric_call(
+                        lambda: error_recorder.record_error(error_type=error_type),
+                        "Failed to record database connect error",
+                    )
+                raise
             _safe_metric_call(
                 lambda: metrics.record_checkout_wait(duration=time.perf_counter() - started),
                 "Failed to record database checkout wait",
             )
             return connection
 
+        def _reported_by_handle_error(self, exc: Exception) -> bool:
+            """Whether the engine turns ``exc`` into a ``handle_error`` event itself."""
+            dbapi = getattr(self._dialect, "loaded_dbapi", None)
+            return dbapi is not None and isinstance(exc, dbapi.Error)
+
     setattr(InstrumentedPool, _WAIT_RECORDER_ATTRIBUTE, metrics)
     InstrumentedPool.__name__ = f"Instrumented{pool_class.__name__}"
     InstrumentedPool.__qualname__ = InstrumentedPool.__name__
@@ -121,6 +168,12 @@ def attach_metrics(engine: AsyncEngine, metrics: PostgresMetricsProtocol) -> Non
     Registers event handlers for connection checkout, checkin, and error events
     to collect pool statistics and connection metrics.
 
+    The pool gauges come from the pool itself: a ``metrics`` that implements
+    ``PoolStatsFunctionRecorder`` is handed functions that read ``engine.pool`` whenever
+    the metrics are collected, so an idle pool reports what it holds rather than its last
+    burst, and a pool recreated by ``dispose()`` is the one read. One that only implements
+    ``record_pool_stats`` is sampled from the ``checkout`` and ``checkin`` events instead.
+
     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
@@ -142,12 +195,24 @@ def attach_metrics(engine: AsyncEngine, metrics: PostgresMetricsProtocol) -> Non
             type(pool).__name__,
         )
 
+    reads_pool_on_collect = False
+    if isinstance(metrics, PoolStatsFunctionRecorder):
+        reads_pool_on_collect = True
+        # engine.pool is looked up on every read: dispose() replaces the pool object.
+        metrics.set_pool_stats_functions(
+            pool_size=lambda: _pool_size(engine.pool),
+            pool_checked_out=lambda: _pool_checked_out(engine.pool),
+            pool_overflow=lambda: _pool_overflow(engine.pool),
+        )
+
     def record_pool_stats() -> None:
+        if reads_pool_on_collect:
+            return
         _safe_metric_call(
             lambda: metrics.record_pool_stats(
-                pool_size=pool.size() if hasattr(pool, "size") else 0,
-                pool_checked_out=(pool.checkedout() if hasattr(pool, "checkedout") else 0),
-                pool_overflow=pool.overflow() if hasattr(pool, "overflow") else 0,
+                pool_size=_pool_size(pool),
+                pool_checked_out=_pool_checked_out(pool),
+                pool_overflow=_pool_overflow(pool),
             ),
             "Failed to record database pool stats",
         )
@@ -170,11 +235,11 @@ def attach_metrics(engine: AsyncEngine, metrics: PostgresMetricsProtocol) -> Non
 
     def on_error(exception_context: Any) -> None:
         """Handle database error event."""
-        exc = exception_context.original_exception
-        error_type = type(exc).__name__
-        is_timeout = isinstance(exc, (TimeoutError, SATimeoutError))
+        # Only errors on an established connection get here -- a statement timeout among
+        # them. Timeouts acquiring a connection are counted by the instrumented pool.
+        error_type = type(exception_context.original_exception).__name__
         _safe_metric_call(
-            lambda: metrics.record_error(error_type=error_type, is_timeout=is_timeout),
+            lambda: metrics.record_error(error_type=error_type),
             "Failed to record database error metric",
         )
 
@@ -226,7 +291,7 @@ class AsyncSessionManager(Generic[SessionT]):
         self,
         url: str,
         echo: bool = False,
-        poolclass: str | type = "null",
+        poolclass: str | type | None = None,
         session_class: type[SessionT] | None = None,
         expire_on_commit: bool = False,
         connect_args: dict[str, object] | None = None,
@@ -244,13 +309,18 @@ class AsyncSessionManager(Generic[SessionT]):
         Args:
             url: Database connection URL (required).
             echo: If True, SQLAlchemy will log all SQL statements (default: False).
-            poolclass: SQLAlchemy pool class or name (default: "null").
-                Use "queue" for production, "null" for testing.
+            poolclass: SQLAlchemy pool class or name. Defaults to ``pool_settings.kind``
+                when ``pool_settings`` is given, otherwise to ``"null"`` -- a new connection
+                for every checkout, which suits tests and scripts. A service wants
+                ``"async_adapted_queue"``. The sync pools (``"queue"``,
+                ``"singleton_thread"``) cannot run on an async engine.
             session_class: Custom ``AsyncSession`` subclass (default: ``AsyncSession``).
             expire_on_commit: If True, objects expire after commit (default: False).
             connect_args: Arguments passed to the database driver (default: None).
             isolation_level: Default transaction isolation level (default: None).
-            pool_settings: Pool configuration settings (default: None).
+            pool_settings: Pool configuration settings (default: None). ``size``,
+                ``max_overflow`` and ``timeout`` apply to the queue pools only; ``recycle``
+                and ``pre_ping`` apply to every pool.
             use_orjson: If True, use orjson for JSON serialization (default: False).
             metrics: Optional metrics collector (default: None). One that also implements
                 ``CheckoutWaitRecorder`` gets the pool class wrapped by
@@ -270,6 +340,8 @@ class AsyncSessionManager(Generic[SessionT]):
         self._closed = False
         self._close_lock = asyncio.Lock()
         self._dispose_timeout = dispose_timeout
+        if poolclass is None:
+            poolclass = pool_settings.kind if pool_settings is not None else "null"
         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

{sqlalchemy_foundation_kit-0.4.0 → sqlalchemy_foundation_kit-0.5.0}/sqlalchemy_foundation_kit/uow/protocols.py

@@ -56,7 +56,7 @@ class AsyncUnitOfWork(Protocol, Generic[T_co]):
     Provides three modes of operation:
         - ``transaction()``: For write operations with automatic commit/rollback.
         - ``managed_session()``: For write operations with **manual** commit/rollback control.
-        - ``query()``: For read-only operations without transaction management.
+        - ``query()``: For reads, in one ``READ ONLY`` transaction that is rolled back on exit.
     """
 
     def transaction(
@@ -95,4 +95,4 @@ class AsyncUnitOfWork(Protocol, Generic[T_co]):
         """
 
     def query(self, isolation_level: str | None = None) -> AbstractAsyncContextManager[T_co]:
-        """Create a read-only query context without transaction management."""
+        """Create a read-only query context: one ``READ ONLY`` transaction, rolled back on exit."""

{sqlalchemy_foundation_kit-0.4.0 → sqlalchemy_foundation_kit-0.5.0}/sqlalchemy_foundation_kit/uow/sqlalchemy.py

@@ -3,12 +3,11 @@
 from __future__ import annotations
 
 import asyncio
-import logging
 from collections.abc import AsyncIterator, Callable
 from contextlib import asynccontextmanager
 from typing import Generic
 
-from sqlalchemy.exc import SQLAlchemyError
+from sqlalchemy import text
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 
 from .._typing import T
@@ -16,8 +15,6 @@ from ..session.locks import try_advisory_xact_lock
 from .enums import IsolationLevel
 from .protocols import AsyncUnitOfWork, AsyncUowTransaction
 
-logger = logging.getLogger(__name__)
-
 # Cache valid isolation levels for performance (avoid recreating set on each call)
 _VALID_ISOLATION_LEVELS: frozenset[str] = frozenset(item.value for item in IsolationLevel)
 
@@ -111,6 +108,23 @@ async def apply_isolation_level(
         await session.connection(execution_options={"isolation_level": normalized})
 
 
+async def _begin_read_only(session: AsyncSession) -> None:
+    """Make the session's transaction ``READ ONLY``.
+
+    The ``postgresql_readonly`` execution option is applied when a connection is checked
+    out, so on a session that has not checked one out yet it goes with that checkout:
+    asyncpg then opens the transaction ``READ ONLY`` with no extra round trip, and the
+    dialect resets the flag when the connection returns to the pool. When ``open_session()``
+    has already started the transaction -- an isolation level was applied, or an override
+    ran a statement -- ``SET TRANSACTION READ ONLY`` marks it instead; PostgreSQL accepts
+    that at any point in a transaction.
+    """
+    if session.in_transaction():
+        await session.execute(text("SET TRANSACTION READ ONLY"))
+    else:
+        await session.connection(execution_options={"postgresql_readonly": True})
+
+
 @asynccontextmanager
 async def _owned_transaction(session: AsyncSession) -> AsyncIterator[None]:
     """Run a block inside a transaction, committing on success and rolling back on failure.
@@ -231,7 +245,7 @@ class AsyncSQLAlchemyUnitOfWork(AsyncUnitOfWork[T], Generic[T]):
 
     Methods:
         transaction(): For write operations with automatic commit/rollback.
-        query(): For read-only operations without transaction management.
+        query(): For reads, in one READ ONLY transaction that is rolled back on exit.
     """
 
     def __init__(
@@ -314,9 +328,11 @@ class AsyncSQLAlchemyUnitOfWork(AsyncUnitOfWork[T], Generic[T]):
             isolation_level: Optional transaction isolation level.
                 Can be an IsolationLevel enum member or a string value.
                 Supported values: "READ_COMMITTED", "REPEATABLE_READ", "SERIALIZABLE", "READ_UNCOMMITTED".
-            flush_before_commit: If True, flush the session before commit to surface
-                constraint violations while still inside the transaction. If ``None`` (default),
-                falls back to the value passed to the constructor (``True`` unless overridden).
+            flush_before_commit: If True, flush the session explicitly before the commit.
+                The commit flushes as well, so a constraint violation raises the same
+                exception through the same rollback either way, as the block exits. If
+                ``None`` (default), falls back to the value passed to the constructor
+                (``True`` unless overridden).
 
         Raises:
             ValueError: If isolation_level is not supported.
@@ -334,13 +350,10 @@ class AsyncSQLAlchemyUnitOfWork(AsyncUnitOfWork[T], Generic[T]):
             uow = self._transaction_factory(session)
             yield uow
             if flush_before_commit:
-                # Flush changes before commit to catch constraint violations early
-                # while still inside the transaction context.
-                try:
-                    await session.flush()
-                except SQLAlchemyError as e:
-                    logger.warning("Database flush failed", extra={"error": str(e)})
-                    raise
+                # A failure propagates to the caller as is, and is not logged here: its
+                # message carries the statement's parameters and PostgreSQL's DETAIL line,
+                # which holds the conflicting row's values.
+                await session.flush()
 
     @asynccontextmanager
     async def managed_session(
@@ -437,11 +450,20 @@ class AsyncSQLAlchemyUnitOfWork(AsyncUnitOfWork[T], Generic[T]):
         self,
         isolation_level: IsolationLevel | str | None = None,
     ) -> AsyncIterator[T]:
-        """Create a read-only query context without transaction management.
+        """Create a read-only query context: one ``READ ONLY`` transaction, never committed.
+
+        The block runs in a single transaction from its first statement until it exits,
+        when the transaction is rolled back. PostgreSQL enforces ``READ ONLY``: an
+        ``INSERT``, ``UPDATE``, ``DELETE`` or DDL statement, and functions such as
+        ``nextval()``, fail with SQLSTATE 25006. Reads, ``SET LOCAL`` / ``set_config`` and
+        advisory locks work.
 
-        This method is designed for read-only operations and does not start a transaction
-        or perform any commit/rollback. It's semantically clearer than managed_session()
-        for read operations.
+        It is still a transaction, with what that costs: every lock it takes -- the
+        ``AccessShareLock`` on each table read, an advisory xact lock -- is held until the
+        block exits, ``now()`` is fixed at the first statement, a slow ``await`` inside the
+        block leaves the connection ``idle in transaction``, and behind a transaction-mode
+        pooler the block holds one server connection from its first statement to exit.
+        Keep it short.
 
         Args:
             isolation_level: Optional transaction isolation level.
@@ -456,13 +478,14 @@ class AsyncSQLAlchemyUnitOfWork(AsyncUnitOfWork[T], Generic[T]):
                 async with uow.query() as qx:
                     users = await qx.users.list_all()
                     user = await qx.users.get_by_id(user_id)
-                # No commit/rollback - just closes session
+                # Rolled back on exit -- there is nothing to commit
 
         Note:
-            While this method is intended for read-only operations, SQLAlchemy does not enforce
-            this at the session level. It's up to the caller to ensure only read operations are performed.
+            Only the block's first transaction is read-only. Calling
+            ``session.commit()`` inside ``query()`` ends it, and the session starts an
+            ordinary one on its next statement. Write in :meth:`transaction` instead.
         """
         async with self.open_session(isolation_level) as session:
-            # No transaction begin/commit - just yield the session
+            await _begin_read_only(session)
             uow = self._transaction_factory(session)
             yield uow

sqlalchemy_foundation_kit-0.4.0/sqlalchemy_foundation_kit/__version__.py

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

sqlalchemy_foundation_kit-0.4.0/sqlalchemy_foundation_kit/session/connection.py

@@ -1,33 +0,0 @@
-"""Custom connection class for pgbouncer compatibility (async)."""
-
-import uuid
-
-import asyncpg
-
-
-class AsyncCConnection(asyncpg.Connection):
-    """Custom async connection class for pgbouncer magic.
-
-    This subclass overrides only the private method _get_unique_id so that
-    prepared statement identifiers are unique per connection. That is required
-    when using pgbouncer in transaction mode, where the same server connection
-    may be reused for different logical connections.
-
-    See: https://github.com/sqlalchemy/sqlalchemy/issues/6467
-    """
-
-    def _get_unique_id(self, prefix: str) -> str:
-        """Generate unique ID for prepared statements.
-
-        Args:
-            prefix: Prefix for the unique ID.
-
-        Returns:
-            A unique string ID including the prefix and a UUID.
-        """
-        return f"__asyncpg_{prefix}_{uuid.uuid4()}__"
-
-
-__all__ = [
-    "AsyncCConnection",
-]