pgsqlasync2fast-fastapi 0.4.1__tar.gz → 0.5.0__tar.gz

{pgsqlasync2fast_fastapi-0.4.1/src/pgsqlasync2fast_fastapi.egg-info → pgsqlasync2fast_fastapi-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgsqlasync2fast-fastapi
-Version: 0.4.1
+Version: 0.5.0
 Summary: Simple and fast PostgreSQL async module for FastAPI with multi-database support
 Author-email: Angel Daniel Sanchez Castillo <angeldaniel.sanchezcastillo@gmail.com>
 License: MIT License
@@ -50,6 +50,7 @@ Requires-Dist: sqlalchemy>=2.0.0
 Requires-Dist: sqlmodel>=0.0.22
 Requires-Dist: asyncpg>=0.29.0
 Requires-Dist: greenlet>=3.0.0
+Requires-Dist: alembic==1.20.0
 Dynamic: license-file
 
 # pgsqlasync2fast-fastapi

{pgsqlasync2fast_fastapi-0.4.1 → pgsqlasync2fast_fastapi-0.5.0}/pyproject.toml

@@ -34,6 +34,9 @@ dependencies = [
     "sqlmodel>=0.0.22",
     "asyncpg>=0.29.0",
     "greenlet>=3.0.0",
+    # Exact pin per the alembic-2fast migration change: deliberate re-pins
+    # require a version bump and a full test run. Never use a range here.
+    "alembic==1.20.0",
 ]
 
 [dependency-groups]
@@ -72,6 +75,9 @@ version = {attr = "pgsqlasync2fast_fastapi.__version__.__version__"}
 [tool.setuptools.package-data]
 pgsqlasync2fast_fastapi = [
     "skills/*.md",
+    # Shared Alembic env implementation + any future chain data shipped as
+    # wheel package data (resolved from the installed release, never a checkout).
+    "migrations/**/*.py",
 ]
 
 [tool.pytest.ini_options]

{pgsqlasync2fast_fastapi-0.4.1 → pgsqlasync2fast_fastapi-0.5.0}/src/pgsqlasync2fast_fastapi/__init__.py

@@ -56,6 +56,17 @@ from pgsqlasync2fast_fastapi.seeder import (
     sync_table_sequence,
 )
 
+# Re-export migration-specific exports
+from pgsqlasync2fast_fastapi.migrations import (
+    # Chain spec + runner
+    ChainSpec,
+    run_migrations,
+    # Lane-keyed chain registry
+    register_chain,
+    get_lane_chains,
+    clear_chain_registry,
+)
+
 __all__ = [
     # Version
     "__version__",
@@ -94,4 +105,10 @@ __all__ = [
     "insert_if_missing",
     # Shared PostgreSQL sequence re-sync primitive
     "sync_table_sequence",
+    # Migration infrastructure (alembic-2fast)
+    "ChainSpec",
+    "run_migrations",
+    "register_chain",
+    "get_lane_chains",
+    "clear_chain_registry",
 ]

pgsqlasync2fast_fastapi-0.5.0/src/pgsqlasync2fast_fastapi/__version__.py

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

pgsqlasync2fast_fastapi-0.5.0/src/pgsqlasync2fast_fastapi/migrations/__init__.py

@@ -0,0 +1,49 @@
+"""
+pgsqlasync2fast_fastapi.migrations - shared Alembic infrastructure for the
+2fast family.
+
+This package ships the shared pieces of the ``alembic-2fast`` migration
+overhaul (Metal ERP change):
+
+- ``env.py`` - shared async env implementation (official Alembic async recipe:
+  ``async_engine_from_config`` + ``NullPool`` + ``dispose()`` per run). Each
+  consumer chain dir ships a thin ``env.py`` shim that imports
+  ``run_migrations_offline`` / ``run_migrations_online`` from here.
+- ``registry.py`` - lane-keyed chain registry (``register_chain`` /
+  ``get_lane_chains``), same idiom as ``register_seeder``.
+- ``runner.py`` - ``ChainSpec`` and ``run_migrations(connection_name, chains)``:
+  reads the URL from manager config only (never ``DatabaseManager._engines``)
+  and upgrades each chain to head in declaration order.
+
+Consumers resolve chains from the INSTALLED release via alembic-native
+``pkg:path`` resource strings (``coerce_resource_to_filename``), never from a
+repository checkout.
+"""
+
+from .env import (
+    do_run_migrations,
+    run_async_migrations,
+    run_migrations_offline,
+    run_migrations_online,
+)
+from .registry import (
+    clear_chain_registry,
+    get_lane_chains,
+    register_chain,
+)
+from .runner import ChainSpec, run_migrations
+
+__all__ = [
+    # env impl
+    "do_run_migrations",
+    "run_async_migrations",
+    "run_migrations_offline",
+    "run_migrations_online",
+    # registry
+    "clear_chain_registry",
+    "get_lane_chains",
+    "register_chain",
+    # runner
+    "ChainSpec",
+    "run_migrations",
+]

pgsqlasync2fast_fastapi-0.5.0/src/pgsqlasync2fast_fastapi/migrations/env.py

@@ -0,0 +1,120 @@
+"""
+Shared Alembic async env implementation (design D1 of the ``alembic-2fast``
+change).
+
+Consumer packages ship a ~12-line ``env.py`` shim inside each chain directory
+that imports ``run_migrations_offline`` / ``run_migrations_online`` from this
+module and dispatches on ``context.is_offline_mode()``. Alembic's
+``env_py_location`` is fixed at ``<script_location>/env.py``, so the shared
+logic lives here and the per-chain shims stay thin.
+
+Configuration contract (set programmatically by ``runner._chain_config``):
+
+- main option ``script_location`` - ``"<package>:<chain_path>"`` (installed
+  release resolution via ``coerce_resource_to_filename``).
+- main option ``sqlalchemy.url`` - the connection URL (config only).
+- main option ``version_table`` - the chain's version table. Alembic 1.20.0
+  does NOT transport a ``version_table`` main option into ``MigrationContext``
+  (it is read from configure ``opts`` only), so it is passed EXPLICITLY to
+  ``context.configure(version_table=...)`` below (design D1).
+- attribute ``target_metadata`` - chain-owned ``MetaData`` for autogenerate.
+- attributes ``include_object`` / ``include_name`` - ownership filters from
+  ``runner._owner_filter`` (design D9).
+
+Async pattern (official recipe): a fresh engine per run via
+``async_engine_from_config`` with ``NullPool``, disposed after the run. The
+runner executes each chain via ``asyncio.to_thread(command.upgrade, ...)``, so
+every run owns its own event loop in its own worker thread.
+
+IMPORTANT (shared-module reuse): this module is imported ONCE per process
+while Alembic re-executes each chain's ``env.py`` shim on every run. Nothing
+here may bind ``context.config`` at module level - every function resolves
+``context.config`` lazily at call time so each run sees its own ``Config``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from alembic import context
+from sqlalchemy import pool
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+if TYPE_CHECKING:
+    from alembic.config import Config
+
+__all__ = [
+    "do_run_migrations",
+    "run_async_migrations",
+    "run_migrations_offline",
+    "run_migrations_online",
+]
+
+
+def _shared_configure_kwargs(config: "Config") -> dict[str, Any]:
+    """Options shared by the offline and online ``configure`` calls."""
+    kwargs: dict[str, Any] = {
+        "target_metadata": config.attributes.get("target_metadata"),
+        "include_object": config.attributes.get("include_object"),
+        "include_name": config.attributes.get("include_name"),
+    }
+    version_table = config.get_main_option("version_table")
+    if version_table:
+        # Deliberate explicit pass-through: alembic 1.20.0 reads version_table
+        # from the MigrationContext opts only, never from main options.
+        kwargs["version_table"] = version_table
+    return kwargs
+
+
+def do_run_migrations(connection: Connection) -> None:
+    """Configure ``context`` for an online run against ``connection``."""
+    config = context.config
+    context.configure(
+        connection=connection,
+        **_shared_configure_kwargs(config),
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_offline() -> None:
+    """Render the chain's SQL without a database connection (offline mode)."""
+    config = context.config
+    kwargs = _shared_configure_kwargs(config)
+    kwargs.update(
+        {
+            "url": config.get_main_option("sqlalchemy.url"),
+            "literal_binds": True,
+            "dialect_opts": {"paramstyle": "named"},
+        }
+    )
+    context.configure(**kwargs)
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    """Fresh NullPool async engine, upgraded, disposed - all per run."""
+    config = context.config
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    """Entry point called by chain shims in online mode.
+
+    Runs in the worker thread that ``runner.run_migrations`` spawned via
+    ``asyncio.to_thread``, so no event loop is running here and
+    ``asyncio.run`` owns a fresh loop (and therefore the engine) per run.
+    """
+    asyncio.run(run_async_migrations())

pgsqlasync2fast_fastapi-0.5.0/src/pgsqlasync2fast_fastapi/migrations/registry.py

@@ -0,0 +1,70 @@
+"""
+Lane-keyed chain registry (design D6 of the ``alembic-2fast`` change).
+
+Mirrors the ``register_seeder`` idiom: consumers register their chain specs at
+import time, the app composes lanes explicitly, and the runner executes them
+in registration order per lane.
+
+- AUTH lane orders ``oauth`` -> ``permissions-global`` -> ``tenant2fast-auth``
+  (FK-proven); registration order within a lane is preserved.
+- TENANT lane chains (``tenant2fast-rbac``, ``app``) are order-independent;
+  callers may still declare an explicit preferred order.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .runner import ChainSpec
+
+__all__ = [
+    "clear_chain_registry",
+    "get_lane_chains",
+    "register_chain",
+]
+
+_CHAIN_REGISTRY: dict[str, list["ChainSpec"]] = {}
+
+
+def register_chain(lane: str, chain: "ChainSpec") -> None:
+    """
+    Register a chain spec under a lane.
+
+    Re-registering the same ``(package, script_path)`` key updates that entry
+    in place (idempotent, position preserved); a distinct chain appends.
+    Order of registration is the order ``get_lane_chains`` returns, which is
+    the execution order for ordering-sensitive lanes.
+
+    Args:
+        lane: Lane name, e.g. ``"auth"`` or ``"tenant"``.
+        chain: The chain spec to register.
+    """
+    chains = _CHAIN_REGISTRY.setdefault(lane, [])
+    for index, existing in enumerate(chains):
+        if (
+            existing.package == chain.package
+            and existing.script_path == chain.script_path
+        ):
+            chains[index] = chain
+            return
+    chains.append(chain)
+
+
+def get_lane_chains(lane: str) -> list["ChainSpec"]:
+    """
+    Return a defensive copy of the chains registered for a lane.
+
+    Args:
+        lane: Lane name, e.g. ``"auth"`` or ``"tenant"``.
+
+    Returns:
+        List of ``ChainSpec`` objects in registration order (empty if none).
+    """
+    return list(_CHAIN_REGISTRY.get(lane, []))
+
+
+def clear_chain_registry() -> None:
+    """Clear all registered chains. Useful for testing."""
+    global _CHAIN_REGISTRY
+    _CHAIN_REGISTRY = {}

pgsqlasync2fast_fastapi-0.5.0/src/pgsqlasync2fast_fastapi/migrations/runner.py

@@ -0,0 +1,163 @@
+"""
+Async migration runner for package-owned Alembic chains (design D3 of the
+``alembic-2fast`` change).
+
+``run_migrations(connection_name, chains)`` upgrades each chain to ``head``
+in declaration order. Key properties:
+
+- URL resolution is CONFIG-ONLY: ``manager.config.get_connection_url(name)``.
+  ``DatabaseManager._engines`` (pooled app engines) is never read or reused -
+  each chain run gets a fresh ``NullPool`` async engine inside env.py that is
+  disposed after the run.
+- Each chain runs in a worker thread via ``asyncio.to_thread``, so env.py's
+  ``asyncio.run`` owns a fresh event loop (and engine) per run - it can never
+  collide with the app's lifespan loop.
+- ``script_location`` is an alembic-native ``"<package>:<chain_path>"``
+  resource string: Alembic resolves it from the INSTALLED release via
+  ``coerce_resource_to_filename`` (importlib.resources), never from a
+  checkout.
+- Ownership filtering (design D9): ``include_object`` / ``include_name``
+  attributes admit only tables (and their child objects) listed in
+  ``owned_tables``, so autogenerate on a shared ``MetaData`` never proposes
+  foreign tables.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, Callable, Sequence
+
+from alembic import command
+from alembic.config import Config
+from sqlalchemy import MetaData
+
+from ..connection import get_manager
+
+__all__ = [
+    "ChainSpec",
+    "run_migrations",
+]
+
+#: Object types whose ownership derives from their parent table (type names
+#: verified against alembic 1.20.0 ``NameFilterType``).
+_OWNED_PARENT_TYPES = frozenset(
+    {
+        "index",
+        "unique_constraint",
+        "foreign_key_constraint",
+        "check_constraint",
+    }
+)
+
+
+@dataclass(frozen=True)
+class ChainSpec:
+    """
+    Description of one package-owned Alembic chain shipped inside a wheel.
+
+    Attributes:
+        package: Import name of the wheel's package, e.g. ``"oauth2fast_fastapi"``.
+        script_path: Chain directory inside the package, e.g. ``"migrations/oauth"``.
+        version_table: Name of the chain's version table, e.g.
+            ``"alembic_version_oauth"`` (per-chain, never the default).
+        target_metadata: Chain-owned ``MetaData`` for autogenerate comparison.
+        owned_tables: Table names this chain owns; the autogenerate ownership
+            filter admits only these (design D9).
+    """
+
+    package: str
+    script_path: str
+    version_table: str
+    target_metadata: MetaData
+    owned_tables: frozenset[str]
+
+
+def _owner_filter(owned_tables: frozenset[str]) -> Callable[..., bool]:
+    """
+    Build an ownership filter usable for BOTH alembic include hooks (D9).
+
+    Alembic calls ``include_object`` with
+    ``(object_, name, type_, reflected, compare_to)`` and ``include_name``
+    with ``(name, type_, parent_names)``; the returned callable dispatches on
+    the argument count:
+
+    - ``type_ == "table"`` -> the table's own name must be owned.
+    - index / unique / FK / check constraint -> the object's *parent table*
+      must be owned (no cross-lane objects are proposed).
+    - anything else -> admitted.
+
+    Args:
+        owned_tables: Table names owned by the chain.
+
+    Returns:
+        A callable assigning to ``cfg.attributes["include_object"]`` and
+        ``cfg.attributes["include_name"]``.
+    """
+
+    def _filter(*args: Any) -> bool:
+        if len(args) == 3:  # include_name(name, type_, parent_names)
+            name, type_, parent_names = args
+            parent_table = None
+        else:  # include_object(object_, name, type_, reflected, compare_to)
+            object_, name, type_, _, _ = args
+            parent_table = getattr(object_, "table", None)
+
+        if type_ == "table":
+            return name in owned_tables
+        if type_ in _OWNED_PARENT_TYPES:
+            if parent_table is not None:
+                return parent_table.name in owned_tables
+            return parent_names.get("table_name") in owned_tables
+        return True
+
+    return _filter
+
+
+def _chain_config(chain: ChainSpec, url: str) -> Config:
+    """
+    Build the programmatic Alembic ``Config`` for one chain run (no ini file).
+
+    Args:
+        chain: The chain spec to configure.
+        url: The connection URL (already resolved from manager config).
+
+    Returns:
+        A ``Config`` whose main options and attributes drive the shared env.
+    """
+    cfg = Config()
+    cfg.set_main_option(
+        "script_location", f"{chain.package}:{chain.script_path}"
+    )
+    cfg.set_main_option("sqlalchemy.url", url)
+    cfg.set_main_option("version_table", chain.version_table)
+    cfg.attributes["target_metadata"] = chain.target_metadata
+    cfg.attributes["include_object"] = _owner_filter(chain.owned_tables)
+    cfg.attributes["include_name"] = _owner_filter(chain.owned_tables)
+    return cfg
+
+
+async def run_migrations(
+    connection_name: str, chains: Sequence[ChainSpec]
+) -> None:
+    """
+    Upgrade every chain to head for a named connection, in declared order.
+
+    Args:
+        connection_name: Named connection from the manager config (e.g.
+            ``"auth"``, ``"tenant_1"``).
+        chains: Chain specs to apply, in FK-proven order.
+
+    Raises:
+        ValueError: If the connection name is not configured.
+        Any exception raised by Alembic's ``command.upgrade`` (fail-fast per
+        chain; the caller decides lane error policy).
+    """
+    manager = get_manager()
+    # Config only - pooled app engines under manager._engines are never used.
+    url = manager.config.get_connection_url(connection_name)
+
+    for chain in chains:
+        await asyncio.to_thread(
+            command.upgrade, _chain_config(chain, url), "head"
+        )

{pgsqlasync2fast_fastapi-0.4.1 → pgsqlasync2fast_fastapi-0.5.0}/src/pgsqlasync2fast_fastapi/skills/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: pgsqlasync2fast-fastapi
-description: "Trigger: working on or with pgsqlasync2fast-fastapi. Multi-database async engine manager for FastAPI: DB_CONNECTIONS config, get_db_session deps, seeder orchestrator, tenant engines. Prevails over the 2fast-handbook base skill for this package."
+description: "Trigger: working on or with pgsqlasync2fast-fastapi. Multi-database async engine manager for FastAPI: DB_CONNECTIONS config, get_db_session deps, seeder orchestrator, tenant engines, shared Alembic migration runner. Prevails over the 2fast-handbook base skill for this package."
 license: MIT
 metadata:
   author: AngelDanielSanchezCastillo
-  version: "2.1"
+  version: "2.2"
 ---
 
 ## Purpose
@@ -33,6 +33,12 @@ engines/session factories keyed by connection name (`default`, `auth`,
   reuse this instead of hand-rolling per package (RBAC standardization D2). No
   commit — caller owns the transaction boundary. Also re-exported from the top-level
   `pgsqlasync2fast_fastapi` package.
+- Migration infra (`pgsqlasync2fast_fastapi.migrations`, alembic-2fast change):
+  - `ChainSpec(package, script_path, version_table, target_metadata, owned_tables)` — frozen spec of one wheel-shipped chain.
+  - `register_chain(lane, chain)` / `get_lane_chains(lane)` / `clear_chain_registry()` — lane-keyed registry, same idiom as `register_seeder` (same-key re-registration updates in place; registration order = execution order).
+  - `run_migrations(connection_name, chains)` — async runner per the OFFICIAL alembic recipe: URL config-only (`manager.config.get_connection_url`), each chain upgraded to `head` via `asyncio.to_thread`; shared `migrations/env.py` creates a fresh `async_engine_from_config` + `NullPool` engine and disposes it per run. **NEVER touches `DatabaseManager._engines`** (pooled app engines).
+  - env contract: `script_location` = `"<pkg>:<chain_path>"` resource string resolved from the INSTALLED release (alembic `coerce_resource_to_filename`), never a checkout; `version_table` read via `config.get_main_option` and passed EXPLICITLY to `context.configure(version_table=...)` (alembic 1.20.0 does not auto-transport it); include_object/include_name ownership filters admit only `owned_tables` (+ their indexes/constraints).
+  - `alembic==1.20.0` pinned EXACTLY in runtime deps (deliberate re-pin rule).
 
 ## Architecture
 

{pgsqlasync2fast_fastapi-0.4.1 → pgsqlasync2fast_fastapi-0.5.0/src/pgsqlasync2fast_fastapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgsqlasync2fast-fastapi
-Version: 0.4.1
+Version: 0.5.0
 Summary: Simple and fast PostgreSQL async module for FastAPI with multi-database support
 Author-email: Angel Daniel Sanchez Castillo <angeldaniel.sanchezcastillo@gmail.com>
 License: MIT License
@@ -50,6 +50,7 @@ Requires-Dist: sqlalchemy>=2.0.0
 Requires-Dist: sqlmodel>=0.0.22
 Requires-Dist: asyncpg>=0.29.0
 Requires-Dist: greenlet>=3.0.0
+Requires-Dist: alembic==1.20.0
 Dynamic: license-file
 
 # pgsqlasync2fast-fastapi

{pgsqlasync2fast_fastapi-0.4.1 → pgsqlasync2fast_fastapi-0.5.0}/src/pgsqlasync2fast_fastapi.egg-info/SOURCES.txt

@@ -27,9 +27,14 @@ src/pgsqlasync2fast_fastapi.egg-info/SOURCES.txt
 src/pgsqlasync2fast_fastapi.egg-info/dependency_links.txt
 src/pgsqlasync2fast_fastapi.egg-info/requires.txt
 src/pgsqlasync2fast_fastapi.egg-info/top_level.txt
+src/pgsqlasync2fast_fastapi/migrations/__init__.py
+src/pgsqlasync2fast_fastapi/migrations/env.py
+src/pgsqlasync2fast_fastapi/migrations/registry.py
+src/pgsqlasync2fast_fastapi/migrations/runner.py
 src/pgsqlasync2fast_fastapi/skills/SKILL.md
 tests/test_completo.py
 tests/test_insert_if_missing.py
+tests/test_migration_chains.py
 tests/test_seeder.py
 tests/test_seeder_override.py
 tests/test_sync_sequence.py

{pgsqlasync2fast_fastapi-0.4.1 → pgsqlasync2fast_fastapi-0.5.0}/src/pgsqlasync2fast_fastapi.egg-info/requires.txt

@@ -5,3 +5,4 @@ sqlalchemy>=2.0.0
 sqlmodel>=0.0.22
 asyncpg>=0.29.0
 greenlet>=3.0.0
+alembic==1.20.0

pgsqlasync2fast_fastapi-0.5.0/tests/test_migration_chains.py

@@ -0,0 +1,411 @@
+"""
+Tests for the shared Alembic migration infrastructure (pgsqlasync2fast-fastapi).
+
+This module verifies the runner + chain registry shipped by this package for
+the 2fast-family migration overhaul (Metal ERP change ``alembic-2fast``):
+
+1. ``ChainSpec`` — frozen dataclass describing an installed wheel's chain.
+2. ``register_chain`` / ``get_lane_chains`` / ``clear_chain_registry`` —
+   lane-keyed chain registry (same idiom as ``register_seeder``).
+3. ``run_migrations(connection_name, chains)`` — per-run async engine via
+   ``async_engine_from_config`` + ``NullPool`` + ``dispose()`` in the shared
+   env; the URL comes from ``manager.config`` only and ``DatabaseManager._engines``
+   is NEVER touched.
+4. Shared ``migrations/env.py`` — resolves ``context.config`` lazily per run
+   (the module is imported once per process while alembic re-executes each
+   chain's env.py shim), reads ``version_table`` via
+   ``config.get_main_option("version_table")`` and passes it EXPLICITLY to
+   ``context.configure(version_table=...)``.
+
+No PostgreSQL is required: ``command.upgrade`` is mocked and the env contract
+is asserted at the ``context.configure`` level.
+
+Run with:
+  uv run pytest tests/test_migration_chains.py -v
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from alembic.config import Config
+from contextlib import nullcontext
+from pydantic import SecretStr
+from sqlalchemy import MetaData, pool
+
+from pgsqlasync2fast_fastapi.connection import DatabaseManager
+from pgsqlasync2fast_fastapi.migrations import (
+    ChainSpec,
+    clear_chain_registry,
+    get_lane_chains,
+    register_chain,
+    run_migrations,
+)
+from pgsqlasync2fast_fastapi.settings import DatabaseConnectionSettings, DatabaseSettings
+
+
+@pytest.fixture(autouse=True)
+def clear_chains():
+    """Clear the chain registry before and after each test."""
+    clear_chain_registry()
+    yield
+    clear_chain_registry()
+
+
+def _chain(
+    package: str = "oauth2fast_fastapi",
+    script_path: str = "migrations/oauth",
+    version_table: str = "alembic_version_oauth",
+    owned: tuple[str, ...] = ("users", "roles"),
+) -> ChainSpec:
+    return ChainSpec(
+        package=package,
+        script_path=script_path,
+        version_table=version_table,
+        target_metadata=MetaData(),
+        owned_tables=frozenset(owned),
+    )
+
+
+def _manager_with_auth() -> DatabaseManager:
+    """Database manager whose config holds a single 'auth' connection."""
+    config = DatabaseSettings(
+        connections={
+            "auth": DatabaseConnectionSettings(
+                host="localhost",
+                port=5433,
+                username="mig_user",
+                password=SecretStr("mig_pass"),
+                database="authdb",
+            )
+        }
+    )
+    return DatabaseManager(config)
+
+
+# ============================================================================
+# Registry: register_chain / get_lane_chains / clear_chain_registry
+# ============================================================================
+
+
+def test_register_and_get_lane_chains_preserve_registration_order():
+    oauth = _chain()
+    permissions = _chain(
+        package="permissions2fast_fastapi",
+        script_path="migrations/permissions-global",
+        version_table="alembic_version_permissions",
+    )
+
+    register_chain("auth", oauth)
+    register_chain("auth", permissions)
+
+    assert get_lane_chains("auth") == [oauth, permissions]
+    assert get_lane_chains("tenant") == []
+
+
+def test_register_chain_same_key_updates_in_place():
+    register_chain("auth", _chain(version_table="alembic_version_oauth"))
+
+    updated = _chain(version_table="alembic_version_oauth_v2")
+    register_chain("auth", updated)
+
+    chains = get_lane_chains("auth")
+    assert chains == [updated]  # same position, same key, not duplicated
+
+
+def test_get_lane_chains_returns_defensive_copy():
+    register_chain("auth", _chain())
+
+    chains = get_lane_chains("auth")
+    chains.clear()
+
+    assert len(get_lane_chains("auth")) == 1
+
+
+def test_clear_chain_registry_empties_all_lanes():
+    register_chain("auth", _chain())
+    register_chain("tenant", _chain(version_table="alembic_version_tenant_auth"))
+
+    clear_chain_registry()
+
+    assert get_lane_chains("auth") == []
+    assert get_lane_chains("tenant") == []
+
+
+def test_chain_spec_is_frozen():
+    chain = _chain()
+    with pytest.raises(Exception):
+        chain.version_table = "alembic_version_other"
+
+
+# ============================================================================
+# _owner_filter: include_object / include_name ownership semantics
+# ============================================================================
+
+
+def test_owner_filter_admits_only_owned_tables():
+    from pgsqlasync2fast_fastapi.migrations.runner import _owner_filter
+
+    owned = frozenset({"users"})
+    owner = _owner_filter(owned)
+
+    users = MagicMock()
+    users.name = "users"
+    roles = MagicMock()
+    roles.name = "roles"
+
+    # include_object(object_, name, type_, reflected, compare_to)
+    assert owner(users, "users", "table", False, None) is True
+    assert owner(roles, "roles", "table", False, None) is False
+
+
+def test_owner_filter_constraints_follow_owning_table():
+    from pgsqlasync2fast_fastapi.migrations.runner import _owner_filter
+
+    owner = _owner_filter(frozenset({"users"}))
+
+    owned_idx = MagicMock()
+    owned_idx.table = MagicMock()
+    owned_idx.table.name = "users"
+    foreign_idx = MagicMock()
+    foreign_idx.table = MagicMock()
+    foreign_idx.table.name = "roles"
+
+    # include_object on index/constraint types dispatches by parent table
+    assert owner(owned_idx, "ix_users_a", "index", False, None) is True
+    assert owner(foreign_idx, "ix_roles_a", "index", False, None) is False
+
+
+def test_owner_filter_include_name_reflected_signature():
+    from pgsqlasync2fast_fastapi.migrations.runner import _owner_filter
+
+    owner = _owner_filter(frozenset({"users"}))
+
+    # include_name(name, type_, parent_names)
+    assert owner("users", "table", {}) is True
+    assert owner("roles", "table", {}) is False
+    assert owner("ix_users_a", "index", {"table_name": "users"}) is True
+    assert owner("ix_roles_a", "index", {"table_name": "roles"}) is False
+
+
+# ============================================================================
+# _chain_config: programmatic alembic Config per chain
+# ============================================================================
+
+
+def test_chain_config_sets_script_location_url_and_version_table():
+    from pgsqlasync2fast_fastapi.migrations.runner import _chain_config
+
+    cfg = _chain_config(_chain(), "postgresql+asyncpg://u:p@h:5432/authdb")
+
+    assert cfg.get_main_option("script_location") == "oauth2fast_fastapi:migrations/oauth"
+    assert cfg.get_main_option("sqlalchemy.url") == "postgresql+asyncpg://u:p@h:5432/authdb"
+    assert cfg.get_main_option("version_table") == "alembic_version_oauth"
+    assert cfg.attributes["target_metadata"] is not None
+    assert callable(cfg.attributes["include_object"])
+    assert callable(cfg.attributes["include_name"])
+
+
+# ============================================================================
+# run_migrations: config-only URL, per-chain async upgrade, no pooled engines
+# ============================================================================
+
+
+@pytest.mark.asyncio
+async def test_run_migrations_applies_chains_in_order_with_config_url():
+    manager = _manager_with_auth()
+    oauth = _chain()
+    permissions = _chain(
+        package="permissions2fast_fastapi",
+        script_path="migrations/permissions-global",
+        version_table="alembic_version_permissions",
+    )
+
+    with (
+        patch("pgsqlasync2fast_fastapi.migrations.runner.get_manager", return_value=manager),
+        patch("pgsqlasync2fast_fastapi.migrations.runner.command.upgrade") as mock_upgrade,
+    ):
+        await run_migrations("auth", [oauth, permissions])
+
+    assert mock_upgrade.call_count == 2
+    first_cfg, first_rev = mock_upgrade.call_args_list[0].args
+    second_cfg, second_rev = mock_upgrade.call_args_list[1].args
+
+    assert first_rev == "head"
+    assert second_rev == "head"
+    assert first_cfg.get_main_option("script_location") == "oauth2fast_fastapi:migrations/oauth"
+    assert second_cfg.get_main_option("script_location") == "permissions2fast_fastapi:migrations/permissions-global"
+    assert first_cfg.get_main_option("version_table") == "alembic_version_oauth"
+    assert second_cfg.get_main_option("version_table") == "alembic_version_permissions"
+
+    expected_url = "postgresql+asyncpg://mig_user:mig_pass@localhost:5433/authdb"
+    assert first_cfg.get_main_option("sqlalchemy.url") == expected_url
+    assert second_cfg.get_main_option("sqlalchemy.url") == expected_url
+
+
+@pytest.mark.asyncio
+async def test_run_migrations_never_touches_pooled_engines():
+    manager = _manager_with_auth()
+
+    with (
+        patch("pgsqlasync2fast_fastapi.migrations.runner.get_manager", return_value=manager),
+        patch("pgsqlasync2fast_fastapi.migrations.runner.command.upgrade"),
+    ):
+        await run_migrations("auth", [_chain()])
+
+    # The pooled engine registry must remain untouched: app traffic keeps its
+    # engines, migrations get a fresh NullPool engine created/disposed per run.
+    assert manager._engines == {}
+    assert manager._session_makers == {}
+
+
+# ============================================================================
+# Shared env: version_table pass-through, NullPool, dispose per run, lazy config
+# ============================================================================
+
+
+def test_env_do_run_migrations_passes_version_table_explicitly(monkeypatch):
+    import pgsqlasync2fast_fastapi.migrations.env as env_mod
+
+    cfg = Config()
+    cfg.set_main_option("version_table", "alembic_version_oauth")
+    cfg.attributes["target_metadata"] = MetaData()
+    include_object = MagicMock(return_value=True)
+    include_name = MagicMock(return_value=True)
+    cfg.attributes["include_object"] = include_object
+    cfg.attributes["include_name"] = include_name
+
+    captured: dict = {}
+
+    class FakeContext:
+        config = cfg
+
+        def configure(self, **kwargs):
+            captured.update(kwargs)
+
+        def begin_transaction(self):
+            return nullcontext()
+
+        def run_migrations(self):
+            return None
+
+    monkeypatch.setattr(env_mod, "context", FakeContext())
+
+    env_mod.do_run_migrations(connection=MagicMock())
+
+    # version_table is passed EXPLICITLY — alembic 1.20.0 does not transport
+    # the main option into MigrationContext on its own (design D1).
+    assert captured["version_table"] == "alembic_version_oauth"
+    assert captured["target_metadata"] is cfg.attributes["target_metadata"]
+    assert captured["include_object"] is include_object
+    assert captured["include_name"] is include_name
+    assert captured["connection"] is not None
+
+
+def test_env_offline_configure_uses_url_and_version_table(monkeypatch):
+    import pgsqlasync2fast_fastapi.migrations.env as env_mod
+
+    cfg = Config()
+    cfg.set_main_option("sqlalchemy.url", "postgresql+asyncpg://u:p@h:5432/authdb")
+    cfg.set_main_option("version_table", "alembic_version_oauth")
+
+    captured: dict = {}
+
+    class FakeContext:
+        config = cfg
+
+        def configure(self, **kwargs):
+            captured.update(kwargs)
+
+        def begin_transaction(self):
+            return nullcontext()
+
+        def run_migrations(self):
+            return None
+
+    monkeypatch.setattr(env_mod, "context", FakeContext())
+
+    env_mod.run_migrations_offline()
+
+    assert captured["url"] == "postgresql+asyncpg://u:p@h:5432/authdb"
+    assert captured["version_table"] == "alembic_version_oauth"
+    assert captured["literal_binds"] is True
+
+
+@pytest.mark.asyncio
+async def test_env_async_uses_nullpool_and_disposes_per_run(monkeypatch):
+    import pgsqlasync2fast_fastapi.migrations.env as env_mod
+
+    cfg = Config()
+    cfg.set_main_option("sqlalchemy.url", "postgresql+asyncpg://u:p@h:5432/authdb")
+
+    connection = MagicMock()
+    connection.run_sync = AsyncMock()
+    engine = MagicMock()
+    # connect() is a SYNC call returning an async context manager, whose
+    # __aenter__ yields the connection used by run_sync.
+    engine.connect = MagicMock()
+    engine.connect.return_value.__aenter__ = AsyncMock(return_value=connection)
+    engine.connect.return_value.__aexit__ = AsyncMock(return_value=False)
+    engine.dispose = AsyncMock()
+
+    seen: dict = {}
+
+    def fake_async_engine_from_config(section, prefix, poolclass):
+        seen["prefix"] = prefix
+        seen["poolclass"] = poolclass
+        return engine
+
+    monkeypatch.setattr(env_mod, "async_engine_from_config", fake_async_engine_from_config)
+    monkeypatch.setattr(env_mod, "context", SimpleNamespace(config=cfg))
+
+    await env_mod.run_async_migrations()
+
+    assert seen["prefix"] == "sqlalchemy."
+    assert seen["poolclass"] is pool.NullPool
+    connection.run_sync.assert_awaited_once()
+    engine.dispose.assert_awaited_once()
+
+
+def test_shared_env_resolves_config_lazily_per_run(monkeypatch):
+    """The shared env module is imported once but each chain run must see its
+    own Config — funcions resolve ``context.config`` at call time."""
+    import pgsqlasync2fast_fastapi.migrations.env as env_mod
+
+    captured: list[dict] = []
+
+    class FakeContext:
+        def __init__(self, config):
+            self.config = config
+
+        def configure(self, **kwargs):
+            captured.append(kwargs)
+
+        def begin_transaction(self):
+            return nullcontext()
+
+        def run_migrations(self):
+            return None
+
+    oauth_cfg = Config()
+    oauth_cfg.set_main_option("sqlalchemy.url", "postgresql+asyncpg://u:p@h:5432/authdb")
+    oauth_cfg.set_main_option("version_table", "alembic_version_oauth")
+
+    app_cfg = Config()
+    app_cfg.set_main_option("sqlalchemy.url", "postgresql+asyncpg://u:p@h:5432/appdb")
+    app_cfg.set_main_option("version_table", "alembic_version_app")
+
+    monkeypatch.setattr(env_mod, "context", FakeContext(oauth_cfg))
+    env_mod.run_migrations_offline()
+
+    # Simulate the next chain's run: alembic re-executes the shim with a new
+    # Config; the shared module must NOT be bound to the first run's config.
+    monkeypatch.setattr(env_mod, "context", FakeContext(app_cfg))
+    env_mod.run_migrations_offline()
+
+    assert captured[0]["version_table"] == "alembic_version_oauth"
+    assert captured[0]["url"] == "postgresql+asyncpg://u:p@h:5432/authdb"
+    assert captured[1]["version_table"] == "alembic_version_app"
+    assert captured[1]["url"] == "postgresql+asyncpg://u:p@h:5432/appdb"

pgsqlasync2fast_fastapi-0.4.1/src/pgsqlasync2fast_fastapi/__version__.py

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