Apply migrations on deploy via a Procfile release phase

[f4hy]

Split out of #133, which merged just before this landed on the branch.

Applying the game_night_summary_cache migration to production by hand exposed that there was no release: phase in the Procfile — every migration in this repo was a manual step somebody had to remember, with no failure mode other than noticing. Heroku's release phase is the standard fix (Rails ships release: rails db:migrate, Django manage.py migrate):

release: alembic upgrade head
web: fastapi run radarvan/main.py

It runs after the build, before the new dynos start, and a failing migration fails the release — the old code keeps serving rather than new code booting against a schema it doesn't have.

Three things had to be fixed for it to work at all

Each would have failed the first deploy after adding the line. None is visible from application code, which is probably why the phase never existed.

• alembic was in the dev dependency group. Heroku's buildpack installs uv sync --no-dev, so it wasn't in the slug and the phase would have died with alembic: not found. Moved to [project] dependencies — it's runtime now, not tooling. uv export --no-dev confirms it resolves into the production set (and that mypy/ruff/pytest still don't).
• alembic/env.py didn't normalize postgres://. Heroku's addon-managed DATABASE_URL uses the legacy scheme and SQLAlchemy 2.x has no dialect under that name. db_utils.py and bootstrap_db.py both normalize — but neither helps here, because alembic upgrade re-reads the raw environment variable in its own process, so normalizing before shelling out does nothing for the subprocess. Verified locally: a postgres:// URL now connects where it previously raised.
• env.py printed the full DSN, password included. Release-phase output is app log, readable by anyone with access to the app. Now redacted to user:***@host.

Why bare alembic upgrade head and not scripts/bootstrap_db.py

That script's empty-database branch runs Base.metadata.create_all() + alembic stamp head, which exists for a fresh local Docker volume. On production, unattended, it would silently manufacture a schema instead of failing loudly if DATABASE_URL ever pointed somewhere empty — exactly the failure a release phase takes out of human view. Production always has alembic_version, so the branch is pure downside there.

Caveat worth knowing

Release phase applies the migration while the old dynos are still serving. Additive changes (a new table, a nullable column) are safe; a drop or a rename breaks requests in the window before the swap, and should be split across two deploys. Written up in CLAUDE.md alongside the rest.

Checks

tests/test_deploy_config.py pins all five invariants — the release line, the surviving web line, alembic's dependency group, the scheme normalization, and the redaction. Nothing in application code imports any of them, so a plausible-looking cleanup would otherwise only surface on a push to production.

920 passing, 5 skipped. make all clean.

Note: production is already at b2c9e0a4d715 (head) — that migration was applied by hand before this existed. This changes nothing about the current schema; it means the next one applies itself.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RQ4vgARjcMsiLg3Gk9bnLS