Db Migration

All commands assume you're in the backend folder.

Create an autogenerated migration:

cd backend
uv run alembic revision --autogenerate -m "describe change here"

Apply migrations to the current DB:

cd backend
uv run alembic upgrade head

Rollback last migration (downgrade one step):

cd backend
uv run alembic downgrade -1

View migration history:

cd backend
uv run alembic history --verbose

Rules

• No Edits: Never modify existing migrations; always create new ones.
• Dual-Testing: Include and test both UP and DOWN scripts before committing.
• Audit Scripts: Manually review autogenerated code for errors or omissions.
• Destructive Changes: For drops/deletions, back up data and document the rationale within the script.

Best practices

• Review: Run --autogenerate locally and audit the script in backend/alembic/versions before applying.
• Label: Use clear, descriptive messages (e.g., "add user table").
• Decouple: Separate schema changes from data migrations/backfills; document intent in the script.
• Safety: Prioritize idempotency and avoid destructive actions without a backup.

Testing migrations

• Keep a separate test database for integration tests. Use alembic upgrade head to prepare schema before running tests.
• If a migration includes data transformations, add tests that verify the transformation on a small dataset.

Troubleshooting

• If Alembic cannot detect model changes, ensure the project's alembic/env.py imports the models or the metadata object used by SQLAlchemy.
• For conflicts (multiple branches adding migrations), rebase and create a new consolidated migration if needed, or generate a merge revision using Alembic's merge command.

Reference files

• Alembic revisions live in backend/alembic/versions.
• App models and metadata live in backend/app/database.py.

Done

Follow the commands above for routine migration work. If you want, I can add a small Makefile target or CI job snippet to automate these steps.