Guard against multiple Alembic heads

[level09]

Two branches that each add a migration both parent it on whatever was head at authoring time. Git merges them cleanly because they touch different files, so the break only surfaces as Multiple head revisions are present when flask db upgrade runs on deploy. This happened on #358 and would have failed mid-deploy.

Three small pieces:

• tests/test_migrations.py asserts a single head. Runs in the existing pytest job, needs no database, ~0.1s. A PR that is individually fine but breaks after main moves under it now goes red instead of reaching a server.
• flask doctor reported this case as a yellow ! Could not check migrations because get_current_head() raises on multiple heads and the bare except swallowed it. Switched to get_heads() and made it a hard failure.
• CONTRIBUTING.md documents when to re-parent vs when to flask db merge heads.

Before and after on a simulated two-head branch:

! Could not check migrations: The script directory has multiple heads (due to branching).
- Multiple migration heads (f0a3d6c1, zzz9temp): db upgrade will abort

How to test

1. uv run pytest tests/test_migrations.py passes on a clean tree.
2. Add a migration file with down_revision pointing at any non-head revision, re-run, confirm it fails naming both heads.
3. With that file still present, uv run flask doctor reports the failure line above.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 55a5584c-b8ec-40b1-8b14-8402654f8a8b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/migration-head-guard

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}