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

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

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlalchemy-foundation-kit
-Version: 0.2.1
+Version: 0.3.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}"

{sqlalchemy_foundation_kit-0.2.1 → sqlalchemy_foundation_kit-0.3.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}"

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

@@ -64,7 +64,7 @@ from .uow import (
 try:
     __version__ = version("sqlalchemy-foundation-kit")
 except PackageNotFoundError:  # pragma: no cover
-    __version__ = "0.2.1"
+    __version__ = "0.3.0"
 
 __all__ = [  # noqa: RUF022
     # Base ORM

sqlalchemy_foundation_kit-0.3.0/sqlalchemy_foundation_kit/__version__.py

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

{sqlalchemy_foundation_kit-0.2.1 → sqlalchemy_foundation_kit-0.3.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.3.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.3.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.3.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.3.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,
@@ -23,6 +23,8 @@ from .._typing import SessionT
 from ..base import build_engine_kwargs, resolve_pool_class
 
 if TYPE_CHECKING:
+    from sqlalchemy.engine import Connection
+
     from ..config import PoolSettingsProtocol
     from ..protocols import PostgresMetricsProtocol
 
@@ -100,6 +102,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 +155,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.
@@ -145,6 +177,10 @@ class AsyncSessionManager(Generic[SessionT]):
             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
@@ -174,6 +210,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"