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

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

@@ -1,5 +1,19 @@
 # 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)
+
+
+### Bug Fixes
+
+* the defects the agents page turned up ([#21](https://github.com/bedrock-python/sqlalchemy-foundation-kit/issues/21)) ([9548c72](https://github.com/bedrock-python/sqlalchemy-foundation-kit/commit/9548c72670696dd68e0eeec1f0ae4ad896fa62d6))
+
 ## [0.2.0](https://github.com/bedrock-python/sqlalchemy-foundation-kit/compare/sqlalchemy-foundation-kit-v0.1.0...sqlalchemy-foundation-kit-v0.2.0) (2026-08-28)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlalchemy-foundation-kit
-Version: 0.2.0
+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/
@@ -219,6 +219,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: asyncpg<1.0.0,>=0.30.0
 Requires-Dist: pydantic<3.0.0,>=2.5.0
 Requires-Dist: sqlalchemy[asyncio]<3.0.0,>=2.0.35
 Provides-Extra: all
@@ -279,14 +280,22 @@ Description-Content-Type: text/markdown
 - **Observability** — Prometheus connection-pool metrics and OpenTelemetry tracing
 - **DI integration** — Ready-to-use providers for [`dishka`](https://github.com/reagento/dishka) and `dependency-injector`
 
-Only `sqlalchemy[asyncio]` and `pydantic` are required by default — everything else is an opt-in extra.
+Only `sqlalchemy[asyncio]`, `pydantic` and `asyncpg` are required by default — everything else is an opt-in extra.
+
+> [!TIP]
+> **Building this with an AI assistant?** Hand it
+> **[one page](https://bedrock-python.github.io/sqlalchemy-foundation-kit/agents/)** instead of the
+> whole site: the public API surface, the session-lifetime and transaction-ownership rules that
+> break code when they are broken, the mistakes models actually make with a Unit of Work, and a
+> map of which page to fetch for the rest. Every docs page is also served as raw Markdown at its
+> own URL, and a **Copy page** button at the top of each one hands it straight to a chat window.
 
 ## Key Features
 
 ✅ **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  
@@ -389,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}"
@@ -425,12 +434,14 @@ async def main():
         user = UserDB(id=uuid4(), email="user@example.com", username="user")
         session.add(user)
         # Auto-commit on exit
+
+    await session_manager.aclose()
 ```
 
 ### 4. Unit of Work Pattern
 
 ```python
-from unit_of_work_kit import AsyncSQLAlchemyUnitOfWork, AsyncSQLAlchemyUowTransaction
+from sqlalchemy_foundation_kit import AsyncSQLAlchemyUnitOfWork, AsyncSQLAlchemyUowTransaction
 
 # Define your transaction with repositories
 class MyTransaction(AsyncSQLAlchemyUowTransaction):
@@ -619,6 +630,8 @@ graph LR
 
 Full documentation is available at [https://bedrock-python.github.io/sqlalchemy-foundation-kit/](https://bedrock-python.github.io/sqlalchemy-foundation-kit/)
 
+- [For AI agents](https://bedrock-python.github.io/sqlalchemy-foundation-kit/agents/) — the whole library on one page, for a coding assistant
+
 ## License
 
 This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

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

@@ -29,14 +29,22 @@
 - **Observability** — Prometheus connection-pool metrics and OpenTelemetry tracing
 - **DI integration** — Ready-to-use providers for [`dishka`](https://github.com/reagento/dishka) and `dependency-injector`
 
-Only `sqlalchemy[asyncio]` and `pydantic` are required by default — everything else is an opt-in extra.
+Only `sqlalchemy[asyncio]`, `pydantic` and `asyncpg` are required by default — everything else is an opt-in extra.
+
+> [!TIP]
+> **Building this with an AI assistant?** Hand it
+> **[one page](https://bedrock-python.github.io/sqlalchemy-foundation-kit/agents/)** instead of the
+> whole site: the public API surface, the session-lifetime and transaction-ownership rules that
+> break code when they are broken, the mistakes models actually make with a Unit of Work, and a
+> map of which page to fetch for the rest. Every docs page is also served as raw Markdown at its
+> own URL, and a **Copy page** button at the top of each one hands it straight to a chat window.
 
 ## Key Features
 
 ✅ **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  
@@ -139,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}"
@@ -175,12 +183,14 @@ async def main():
         user = UserDB(id=uuid4(), email="user@example.com", username="user")
         session.add(user)
         # Auto-commit on exit
+
+    await session_manager.aclose()
 ```
 
 ### 4. Unit of Work Pattern
 
 ```python
-from unit_of_work_kit import AsyncSQLAlchemyUnitOfWork, AsyncSQLAlchemyUowTransaction
+from sqlalchemy_foundation_kit import AsyncSQLAlchemyUnitOfWork, AsyncSQLAlchemyUowTransaction
 
 # Define your transaction with repositories
 class MyTransaction(AsyncSQLAlchemyUowTransaction):
@@ -369,6 +379,8 @@ graph LR
 
 Full documentation is available at [https://bedrock-python.github.io/sqlalchemy-foundation-kit/](https://bedrock-python.github.io/sqlalchemy-foundation-kit/)
 
+- [For AI agents](https://bedrock-python.github.io/sqlalchemy-foundation-kit/agents/) — the whole library on one page, for a coding assistant
+
 ## License
 
 This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

{sqlalchemy_foundation_kit-0.2.0 → sqlalchemy_foundation_kit-0.3.0}/pyproject.toml

@@ -31,6 +31,7 @@ classifiers = [
 dependencies = [
     "sqlalchemy[asyncio]>=2.0.35,<3.0.0",
     "pydantic>=2.5.0,<3.0.0",
+    "asyncpg>=0.30.0,<1.0.0",
 ]
 
 [project.urls]
@@ -130,6 +131,10 @@ warn_unreachable = true
 [tool.ruff]
 line-length = 120
 target-version = "py311"
+# The Markdown guides hold fragments -- a keyword argument on its own, a body
+# without its def -- that read as code to a formatter and come out as
+# something else. ruff 0.16 formats fenced Python in Markdown by default.
+extend-exclude = ["*.md"]
 
 [tool.ruff.lint]
 select = ["F", "E", "W", "I", "B", "N", "S", "C4", "DTZ", "SIM", "TRY", "PERF", "RUF", "UP", "ANN", "T20", "PTH", "PLC", "PLE", "PLW"]

{sqlalchemy_foundation_kit-0.2.0 → 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.0"
+    __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.0 → sqlalchemy_foundation_kit-0.3.0}/sqlalchemy_foundation_kit/base/_optional.py

@@ -11,7 +11,7 @@ def require_optional(module_name: str, extra_name: str) -> types.ModuleType:
 
     Args:
         module_name: Name of the module to import (e.g., "orjson", "opentelemetry").
-        extra_name: Name of the pip extra that provides this dependency (e.g., "json", "telemetry").
+        extra_name: Name of the pip extra that provides this dependency (e.g., "orjson", "telemetry").
 
     Returns:
         The imported module.
@@ -20,7 +20,7 @@ def require_optional(module_name: str, extra_name: str) -> types.ModuleType:
         ImportError: If the module is not installed, with installation instructions.
 
     Examples:
-        >>> orjson = require_optional("orjson", "json")
+        >>> orjson = require_optional("orjson", "orjson")
         >>> from opentelemetry import trace
         # or
         >>> otel = require_optional("opentelemetry", "telemetry")

{sqlalchemy_foundation_kit-0.2.0 → sqlalchemy_foundation_kit-0.3.0}/sqlalchemy_foundation_kit/base/serialization.py

@@ -57,7 +57,7 @@ def _json_serializer(obj: object) -> str:
         >>> _json_serializer({"key": "value"})
         '{"key":"value"}'
     """
-    orjson = require_optional("orjson", "json")
+    orjson = require_optional("orjson", "orjson")
 
     try:
         return orjson.dumps(obj, default=_default_json_encoder).decode("utf-8")  # type: ignore[no-any-return]
@@ -82,7 +82,7 @@ def configure_orjson_serialization() -> dict[str, object]:
         >>> "json_deserializer" in config
         True
     """
-    orjson = require_optional("orjson", "json")
+    orjson = require_optional("orjson", "orjson")
 
     return {
         "json_serializer": _json_serializer,

{sqlalchemy_foundation_kit-0.2.0 → 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.3.0/sqlalchemy_foundation_kit/contrib/dependency_injector/_deps.py

@@ -0,0 +1,59 @@
+"""Shared dependency-injector dependency helpers.
+
+Centralizes the dependency-injector import boilerplate and availability check so each
+module doesn't have to repeat it.
+"""
+
+from __future__ import annotations
+
+from typing import Any, NoReturn
+
+
+def check_dependency_injector() -> None:
+    """Raise ImportError if dependency-injector is not installed.
+
+    Raises:
+        ImportError: If dependency-injector is not available.
+    """
+    if not HAS_DEPENDENCY_INJECTOR:
+        raise ImportError(
+            "dependency-injector is required for containers. "
+            "Install it with: pip install 'sqlalchemy-foundation-kit[dependency-injector]'"
+        )
+
+
+class _MissingDependencyInjector:
+    """Stand-in for a dependency-injector name, raising the intended ImportError on first use.
+
+    ``BaseDIContainer`` subclasses ``containers.DeclarativeContainer`` and the container
+    modules build ``providers.*`` in their class bodies, which runs before any check a
+    base class could perform. Without this, importing them without dependency-injector
+    installed fails with ``AttributeError: 'NoneType' object has no attribute
+    'DeclarativeContainer'`` instead of the message that says what to install.
+    """
+
+    def __getattr__(self, name: str) -> NoReturn:
+        check_dependency_injector()
+        raise AttributeError(name)  # pragma: no cover - unreachable, check raises
+
+    def __call__(self, *args: Any, **kwargs: Any) -> NoReturn:
+        check_dependency_injector()
+        raise TypeError("dependency-injector is not installed")  # pragma: no cover - unreachable
+
+
+try:
+    from dependency_injector import containers, providers
+
+    HAS_DEPENDENCY_INJECTOR = True
+except ImportError:
+    HAS_DEPENDENCY_INJECTOR = False
+    containers = _MissingDependencyInjector()  # type: ignore[misc,assignment]
+    providers = _MissingDependencyInjector()  # type: ignore[misc,assignment]
+
+
+__all__ = [
+    "HAS_DEPENDENCY_INJECTOR",
+    "check_dependency_injector",
+    "containers",
+    "providers",
+]

sqlalchemy_foundation_kit-0.3.0/sqlalchemy_foundation_kit/contrib/di/_deps.py

@@ -0,0 +1,53 @@
+"""Shared dishka dependency helpers.
+
+Centralizes the dishka import boilerplate and availability check so each
+provider module doesn't have to repeat it.
+"""
+
+from __future__ import annotations
+
+from typing import Any, NoReturn
+
+
+def check_dishka() -> None:
+    """Raise ImportError if dishka is not installed.
+
+    Raises:
+        ImportError: If dishka is not available.
+    """
+    if not HAS_DISHKA:
+        raise ImportError(
+            "dishka is required for providers. Install it with: pip install 'sqlalchemy-foundation-kit[dishka]'"
+        )
+
+
+class _MissingDishka:
+    """Stand-in for a dishka name, raising the intended ImportError on first use.
+
+    Provider modules read ``Scope.APP`` and apply ``@provide`` in their class bodies,
+    which runs before any check a base class could perform. Without this, importing
+    them without dishka installed fails with ``AttributeError: 'NoneType' object has
+    no attribute 'APP'`` instead of the message that says what to install.
+    """
+
+    def __getattr__(self, name: str) -> NoReturn:
+        check_dishka()
+        raise AttributeError(name)  # pragma: no cover - unreachable, check_dishka raises
+
+    def __call__(self, *args: Any, **kwargs: Any) -> NoReturn:
+        check_dishka()
+        raise TypeError("dishka is not installed")  # pragma: no cover - unreachable
+
+
+try:
+    from dishka import Provider, Scope, provide
+
+    HAS_DISHKA = True
+except ImportError:
+    HAS_DISHKA = False
+    Provider = object  # type: ignore[misc,assignment]
+    Scope = _MissingDishka()  # type: ignore[misc,assignment]
+    provide = _MissingDishka()  # type: ignore[misc,assignment]
+
+
+__all__ = ["HAS_DISHKA", "Provider", "Scope", "check_dishka", "provide"]

{sqlalchemy_foundation_kit-0.2.0 → 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.0 → 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.0 → 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.0 → sqlalchemy_foundation_kit-0.3.0}/sqlalchemy_foundation_kit/session/locks.py

@@ -1,5 +1,7 @@
 """PostgreSQL advisory locks (async)."""
 
+import hashlib
+
 from sqlalchemy import text
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -15,6 +17,10 @@ async def try_advisory_xact_lock(session: AsyncSession, key: str | int) -> bool:
     at transaction end. String keys are hashed to integers. The key is then
     truncated to signed 64-bit as Postgres expects.
 
+    A string key produces the same lock in every process, on every host and in
+    every release of the library, so two replicas of a service asking for
+    ``"nightly-rollup"`` contend for one lock.
+
     Args:
         session: SQLAlchemy AsyncSession within an active transaction.
         key: Lock identifier (string or integer). Strings are hashed to integers.
@@ -31,7 +37,7 @@ async def try_advisory_xact_lock(session: AsyncSession, key: str | int) -> bool:
         ...             await session.commit()
     """
     # Convert string keys to integers via hashing
-    int_key = hash(key) if isinstance(key, str) else key
+    int_key = _hash_lock_key(key) if isinstance(key, str) else key
 
     result = await session.execute(
         text("SELECT pg_try_advisory_xact_lock(:k)"),
@@ -40,6 +46,28 @@ async def try_advisory_xact_lock(session: AsyncSession, key: str | int) -> bool:
     return bool(result.scalar())
 
 
+def _hash_lock_key(key: str) -> int:
+    """Hash a string lock key into the PostgreSQL bigint range, reproducibly.
+
+    Python's built-in ``hash()`` is unusable here: string hashing is salted per
+    interpreter, so the same key becomes a different lock in every process and two
+    replicas of the same service lock nothing against each other. BLAKE2b is
+    deterministic, so the key is stable across processes, hosts and restarts.
+
+    Args:
+        key: Lock identifier.
+
+    Returns:
+        A signed 64-bit integer suitable for ``pg_try_advisory_xact_lock``.
+
+    Examples:
+        >>> _hash_lock_key("nightly-rollup") == _hash_lock_key("nightly-rollup")
+        True
+    """
+    digest = hashlib.blake2b(key.encode("utf-8"), digest_size=8).digest()
+    return int.from_bytes(digest, byteorder="big", signed=True)
+
+
 def _to_signed64(key: int) -> int:
     """Wrap integer to PostgreSQL signed 64-bit bigint range.
 

{sqlalchemy_foundation_kit-0.2.0 → 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)
 
@@ -238,15 +277,18 @@ class AsyncSessionManager(Generic[SessionT]):
         """Get a new database session with automatic transaction management.
 
         Args:
-            isolation_level: Optional isolation level for the transaction.
+            isolation_level: Optional isolation level for the transaction, in the
+                PostgreSQL spelling (``"SERIALIZABLE"``, ``"REPEATABLE READ"``, …).
+                It is applied to the connection this transaction runs on, so it
+                affects only this transaction and not the engine.
 
         Yields:
             Managed async session with active transaction.
         """
         self._ensure_not_closed()
-        options = {"isolation_level": isolation_level} if isolation_level else {}
-        async with (
-            self._session_maker(execution_options=options) as session,
-            session.begin(),
-        ):
+        async with self._session_maker() as session, session.begin():
+            if isolation_level is not None:
+                # begin() has not provisioned a connection yet, so this call is the one
+                # that checks it out -- the only moment the level can still be set.
+                await session.connection(execution_options={"isolation_level": isolation_level})
             yield session

{sqlalchemy_foundation_kit-0.2.0 → sqlalchemy_foundation_kit-0.3.0}/sqlalchemy_foundation_kit/uow/sqlalchemy.py

@@ -74,10 +74,15 @@ async def apply_isolation_level(
 ) -> None:
     """Apply isolation level to an async session's connection.
 
-    **Implementation Detail**:
-    We use ``run_sync()`` because SQLAlchemy's ``execution_options()`` is a
-    synchronous method that configures the underlying DBAPI connection object.
-    We must bridge from async context to sync method via ``run_sync()``.
+    The level has to reach the connection *before* the connection begins its
+    transaction — PostgreSQL cannot change the isolation level of a transaction that
+    is already running, and SQLAlchemy raises ``InvalidRequestError`` if you try. So
+    the level is handed to the ``session.connection()`` call that checks the
+    connection out, which applies it and only then begins.
+
+    Call this on a session that has not yet talked to the database. It starts the
+    session's transaction as a side effect, so a caller that wants to own the
+    transaction should join the one already open rather than call ``session.begin()``.
 
     This is a DRY utility to eliminate duplication of isolation level application
     logic across ``transaction()``, ``managed_session()``, and ``query()`` methods.
@@ -103,9 +108,32 @@ async def apply_isolation_level(
     """
     normalized = normalize_isolation_level(isolation_level)
     if normalized is not None:
-        conn = await session.connection()
-        # run_sync bridges async → sync for DBAPI-level configuration
-        await conn.run_sync(lambda c: c.execution_options(isolation_level=normalized))
+        await session.connection(execution_options={"isolation_level": normalized})
+
+
+@asynccontextmanager
+async def _owned_transaction(session: AsyncSession) -> AsyncIterator[None]:
+    """Run a block inside a transaction, committing on success and rolling back on failure.
+
+    ``session.begin()`` refuses to start a second transaction, and applying an isolation
+    level has to check a connection out — which begins one. So the transaction is only
+    started here when the session does not already have one, and the commit/rollback is
+    driven explicitly instead of by the ``session.begin()`` context manager.
+    """
+    if not session.in_transaction():
+        await session.begin()
+
+    try:
+        yield
+    except BaseException:
+        await session.rollback()
+        raise
+
+    try:
+        await session.commit()
+    except BaseException:
+        await session.rollback()
+        raise
 
 
 class AsyncSQLAlchemyUowTransaction(AsyncUowTransaction):
@@ -181,13 +209,14 @@ class PostgresAdvisoryLockMixin:
 
     session: AsyncSession  # Type annotation for protocol compliance
 
-    async def try_advisory_lock(self, key: int) -> bool:
+    async def try_advisory_lock(self, key: str | int) -> bool:
         """Acquire a Postgres transaction-scoped advisory lock.
 
         Delegates to :func:`try_advisory_xact_lock` for actual locking logic.
 
         Args:
-            key: Integer lock key.
+            key: Lock key. An integer is used as-is; a string is hashed to one
+                reproducibly, so the same string is the same lock in every process.
 
         Returns:
             True if lock was acquired, False if already held by another session.
@@ -301,7 +330,7 @@ class AsyncSQLAlchemyUnitOfWork(AsyncUnitOfWork[T], Generic[T]):
         if flush_before_commit is None:
             flush_before_commit = self._flush_before_commit
 
-        async with self.open_session(isolation_level) as session, session.begin():
+        async with self.open_session(isolation_level) as session, _owned_transaction(session):
             uow = self._transaction_factory(session)
             yield uow
             if flush_before_commit:
@@ -390,8 +419,10 @@ class AsyncSQLAlchemyUnitOfWork(AsyncUnitOfWork[T], Generic[T]):
             rollback when the session closes.
         """
         async with self.open_session(isolation_level) as session:
-            # Start transaction WITHOUT context manager - no auto-commit
-            await session.begin()
+            # Start transaction WITHOUT context manager - no auto-commit.
+            # An isolation level, if one was asked for, has already begun it.
+            if not session.in_transaction():
+                await session.begin()
             try:
                 uow = self._transaction_factory(session)
                 yield uow, session

sqlalchemy_foundation_kit-0.2.0/sqlalchemy_foundation_kit/__version__.py

@@ -1 +0,0 @@
-__version__ = "0.2.0"  # x-release-please-version

sqlalchemy_foundation_kit-0.2.0/sqlalchemy_foundation_kit/contrib/dependency_injector/_deps.py

@@ -1,37 +0,0 @@
-"""Shared dependency-injector dependency helpers.
-
-Centralizes the dependency-injector import boilerplate and availability check so each
-module doesn't have to repeat it.
-"""
-
-from __future__ import annotations
-
-try:
-    from dependency_injector import containers, providers
-
-    HAS_DEPENDENCY_INJECTOR = True
-except ImportError:
-    HAS_DEPENDENCY_INJECTOR = False
-    containers = None  # type: ignore[misc,assignment]
-    providers = None  # type: ignore[misc,assignment]
-
-
-def check_dependency_injector() -> None:
-    """Raise ImportError if dependency-injector is not installed.
-
-    Raises:
-        ImportError: If dependency-injector is not available.
-    """
-    if not HAS_DEPENDENCY_INJECTOR:
-        raise ImportError(
-            "dependency-injector is required for containers. "
-            "Install it with: pip install 'sqlalchemy-foundation-kit[dependency-injector]'"
-        )
-
-
-__all__ = [
-    "HAS_DEPENDENCY_INJECTOR",
-    "check_dependency_injector",
-    "containers",
-    "providers",
-]

sqlalchemy_foundation_kit-0.2.0/sqlalchemy_foundation_kit/contrib/di/_deps.py

@@ -1,32 +0,0 @@
-"""Shared dishka dependency helpers.
-
-Centralizes the dishka import boilerplate and availability check so each
-provider module doesn't have to repeat it.
-"""
-
-from __future__ import annotations
-
-try:
-    from dishka import Provider, Scope, provide
-
-    HAS_DISHKA = True
-except ImportError:
-    HAS_DISHKA = False
-    Provider = object  # type: ignore[misc,assignment]
-    Scope = None  # type: ignore[misc,assignment]
-    provide = None  # type: ignore[misc,assignment]
-
-
-def check_dishka() -> None:
-    """Raise ImportError if dishka is not installed.
-
-    Raises:
-        ImportError: If dishka is not available.
-    """
-    if not HAS_DISHKA:
-        raise ImportError(
-            "dishka is required for providers. Install it with: pip install 'sqlalchemy-foundation-kit[dishka]'"
-        )
-
-
-__all__ = ["HAS_DISHKA", "Provider", "Scope", "check_dishka", "provide"]