Database Migration Runbook

Schema changes are managed with Alembic in backend/alembic.

New database

Run from backend/:

alembic upgrade head
python -m app.db.seed

Existing pre-Alembic database

Do not run app.db.init_db; it is destructive when explicitly enabled.

1. Back up the database.
2. Compare the live schema against backend/alembic/versions/0001_initial_schema.py.
3. If the live schema already matches the baseline, run:

alembic stamp 0001
alembic upgrade head

stamp 0001 tells Alembic the baseline already exists. upgrade head applies later migrations without recreating existing tables.

Rules

• Schema changes go in backend/alembic/versions.
• Seed and one-off data fixes go in backend/scripts or clearly named manual scripts.
• Root-level schema scripts such as update_db.py are legacy and intentionally fail fast.
• Never run destructive reset commands against shared or production databases.