Runbook: Migrations Failing

Trigger

• make migrate fails.
• make migration name=... generates incorrect diff.
• App startup fails due to DB schema mismatch.

Fast triage

1. Confirm .env points at the DB you expect (SQLITE_DB_PATH).
2. Run migration command explicitly: make migrate.
3. Inspect current migration heads: .venv/bin/python -m alembic heads.

Most common causes

• Model changes were made but migration not generated.
• Migration was built with stale or wrong model imports.
• Wrong DB file/path in .env.
• Someone changed the DB by hand; history no longer matches Alembic.

Recovery steps

1. Confirm model import chain includes new/changed model.
2. Generate migration from current models: make migration name=describe_change.
3. Review generated file in alembic/versions/.
4. Apply migration: make migrate.
5. Re-run tests: make test.

Safe rollback strategy (local)

• If the file is wrong and nobody else has it yet, delete it and generate again with fixed models/imports.
• Do not rewrite shared migration history without team agreement.

Exit criteria

• make migrate passes.
• App starts and uses expected schema.
• make test passes.

Follow-up

• If the schema policy is non-obvious, capture it in an ADR.

Page history