fix(v3-ref-seller): run alembic upgrade head at boot (#421) (#733)

* fix(v3-ref-seller): run alembic upgrade head at boot (#421)

Replaces ``Base.metadata.create_all`` at boot in ``app.py`` and
``seed.py`` with ``alembic upgrade head``. ``create_all`` is idempotent
on table existence but blind to column renames, type changes, and new
columns on existing tables — adopters running this example past first
boot were silently dropping schema changes. Running migrations at boot
puts the example on the same evolution path as ``migrate.py`` and CI.

``alembic.command.upgrade`` is synchronous and opens its own engine;
the boot path runs it through ``asyncio.to_thread`` so the async
surface stays unblocked.

Closes #421.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(deps): add alembic to dev extra for v3-ref-seller boot

The v3 reference seller boot path now imports alembic.command at runtime
(replaces Base.metadata.create_all). CI installs .[dev] but didn't pull
alembic, breaking the v3-storyboard CI job with ImportError.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bokelley

examples/v3_reference_seller/README.md

@@ -243,22 +243,16 @@ where the framework picks it up.
   `create_media_buy` async approval path) and webhook delivery.
   Both classes ship in the SDK; this seller's `app.py` uses the
   in-memory variants for fast iteration.
-- **Alembic migrations** — `Base.metadata.create_all` runs at boot
-  (idempotent on table existence). Production sellers wire Alembic
-  (see the Migrations section below).
 - **Admin CRUD API** — separate Starlette app for tenant / agent
   CRUD. Patterns to come; for now use `seed.py` and direct SQL.
 
 ## Migrations
 
-The app boots with `Base.metadata.create_all` — idempotent on table
-existence, but **blind to column renames, type changes, and new columns
-on existing tables**.  For local fast-iteration this is fine.  Once you
-have production data, use Alembic to evolve the schema safely.
-
-> ⚠️ **`create_all` is unsafe for schema evolution once production data
-> exists.** Column renames and type changes applied after first boot
-> will not be detected and will silently leave the schema stale.
+The app boots by running `alembic upgrade head` — column renames,
+type changes, and new columns on existing tables all propagate
+through the migration scripts under `alembic/versions/`. The same
+path runs from `seed.py`, `migrate.py`, and CI, so the schema you
+develop against matches what ships.
 
 ### Install Alembic
 

examples/v3_reference_seller/seed.py

@@ -29,19 +29,42 @@
 
 import asyncio
 import os
+from pathlib import Path
 
 from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
-from src.models import Account, Base, BuyerAgent, Tenant
+from src.models import Account, BuyerAgent, Tenant
+
+
+def _run_alembic_upgrade_head(db_url: str) -> None:
+    """Run ``alembic upgrade head`` against ``db_url``.
+
+    Mirrors the production entrypoint in ``migrate.py`` so seed runs
+    against the same schema-evolution path as production — column
+    renames and type changes propagate instead of being silently
+    skipped by ``Base.metadata.create_all``.
+    """
+    from alembic import command
+    from alembic.config import Config
+
+    ini_path = Path(__file__).parent / "alembic.ini"
+    # env.py reads DATABASE_URL from os.environ; export so the alembic
+    # script picks up the same URL the seed script connects with.
+    os.environ["DATABASE_URL"] = db_url
+    alembic_cfg = Config(str(ini_path))
+    alembic_cfg.set_main_option("sqlalchemy.url", db_url)
+    command.upgrade(alembic_cfg, "head")
 
 
 async def main() -> None:
     db_url = os.environ.get(
         "DATABASE_URL",
         "postgresql+asyncpg://postgres@localhost/adcp",
     )
+    # Run migrations in a thread — alembic.command.upgrade is sync and
+    # opens its own engine, so calling it directly from an async context
+    # is safe via asyncio.to_thread.
+    await asyncio.to_thread(_run_alembic_upgrade_head, db_url)
     engine = create_async_engine(db_url)
-    async with engine.begin() as conn:
-        await conn.run_sync(Base.metadata.create_all)
     sm = async_sessionmaker(engine, expire_on_commit=False)
 
     async with sm() as session:

examples/v3_reference_seller/src/app.py

@@ -6,7 +6,7 @@
 Boot sequence:
 
 1. Connect SQLAlchemy async engine + sessionmaker.
-2. Create schema (idempotent ``Base.metadata.create_all``).
+2. Evolve schema by running ``alembic upgrade head``.
 3. Wire the upstream HTTP client. The platform calls
    :meth:`adcp.decisioning.DecisioningPlatform.upstream_for` per
    request, which builds a pooled :class:`UpstreamHttpClient` from the
@@ -70,7 +70,6 @@
 
 from .audit import make_sink as make_audit_sink
 from .buyer_registry import make_registry as make_buyer_registry
-from .models import Base
 from .platform import V3ReferenceSeller
 from .tenant_router import SqlSubdomainTenantRouter
 
@@ -178,16 +177,41 @@ def validate_token(token: str) -> Principal | None:
     return validate_token
 
 
-async def _bootstrap_schema_and_load_tokens(engine, sessionmaker) -> dict[str, Principal]:
-    """Bootstrap the schema (idempotent ``CREATE TABLE IF NOT EXISTS``)
-    AND load the bearer-token map in the same event loop, then dispose
-    the engine before returning.
+def _run_alembic_upgrade_head(db_url: str) -> None:
+    """Run ``alembic upgrade head`` against ``db_url``.
+
+    Mirrors the production entrypoint in ``migrate.py`` so boot evolves
+    the schema via the same migration scripts adopters run in CI. The
+    previous ``Base.metadata.create_all`` path silently skipped column
+    renames and type changes on existing tables; running migrations at
+    boot eliminates that drift.
+    """
+    from pathlib import Path
+
+    from alembic import command
+    from alembic.config import Config
+
+    ini_path = Path(__file__).resolve().parent.parent / "alembic.ini"
+    # env.py reads DATABASE_URL from os.environ; export so the alembic
+    # script picks up the same URL the app connects with.
+    os.environ["DATABASE_URL"] = db_url
+    alembic_cfg = Config(str(ini_path))
+    alembic_cfg.set_main_option("sqlalchemy.url", db_url)
+    command.upgrade(alembic_cfg, "head")
 
-    Production adopters use Alembic — this entrypoint sticks with
-    ``create_all`` for fast iteration. Token loading happens here
-    (rather than separately) because ``BearerTokenAuth.validate_token``
-    must be sync for ``transport="both"``, so we pay one DB scan at
-    boot and serve every subsequent request from memory.
+
+async def _bootstrap_schema_and_load_tokens(
+    db_url: str, engine, sessionmaker
+) -> dict[str, Principal]:
+    """Run ``alembic upgrade head`` AND load the bearer-token map in
+    the same event loop, then dispose the engine before returning.
+
+    Migrations propagate schema changes (column renames, type changes,
+    new columns on existing tables) that ``create_all`` silently
+    skipped. Token loading happens here (rather than separately)
+    because ``BearerTokenAuth.validate_token`` must be sync for
+    ``transport="both"``, so we pay one DB scan at boot and serve every
+    subsequent request from memory.
 
     asyncpg binds connection-internal Future objects to the loop they
     were opened on. Bootstrapping via ``asyncio.run`` runs on a
@@ -196,9 +220,12 @@ async def _bootstrap_schema_and_load_tokens(engine, sessionmaker) -> dict[str, P
     ``RuntimeError: got Future attached to a different loop`` on the
     first request. Dispose before returning so uvicorn opens a fresh
     pool on its own loop.
+
+    ``alembic.command.upgrade`` is synchronous and opens its own
+    engine; ``asyncio.to_thread`` runs it off the event loop so the
+    async surface stays unblocked.
     """
-    async with engine.begin() as conn:
-        await conn.run_sync(Base.metadata.create_all)
+    await asyncio.to_thread(_run_alembic_upgrade_head, db_url)
     token_map = await _load_token_map(sessionmaker)
     await engine.dispose()
     return token_map
@@ -240,7 +267,7 @@ def main() -> None:
     engine = create_async_engine(db_url, pool_size=10, max_overflow=20)
     sessionmaker = async_sessionmaker(engine, expire_on_commit=False)
 
-    token_map = asyncio.run(_bootstrap_schema_and_load_tokens(engine, sessionmaker))
+    token_map = asyncio.run(_bootstrap_schema_and_load_tokens(db_url, engine, sessionmaker))
 
     router = SqlSubdomainTenantRouter(sessionmaker=sessionmaker)
     audit_sink = make_audit_sink(sessionmaker)

pyproject.toml

@@ -117,6 +117,11 @@ dev = [
     # so we don't need to boot the JS mock-server in the Python pytest
     # CI run.
     "respx>=0.20.0",
+    # v3 reference seller boots `alembic upgrade head` instead of
+    # Base.metadata.create_all so column renames and type changes
+    # propagate. Required at runtime by examples/v3_reference_seller/
+    # src/app.py and seed.py.
+    "alembic>=1.13.0",
 ]
 docs = [
     "pdoc3>=0.10.0",