Alembic Migrations

This project uses async SQLAlchemy 2.0 + Alembic on PostgreSQL. Migrations live in backend/alembic/versions/ and are numbered (0001_…, 0002_…).

Workflow

1. Change the model first in backend/app/db/models/ (Mapped[...] + mapped_column(), __repr__, relationships with ondelete="CASCADE"). Make sure the model is imported in backend/app/db/models/__init__.py so autogenerate sees it.

2. Autogenerate the migration:

   cd backend && uv run alembic revision --autogenerate -m "add <thing>"
   # or: make db-migrate
   

3. ALWAYS review the generated file. Autogenerate is a draft, not the truth:

   • Confirm upgrade() matches your intent and downgrade() actually reverses it.
   • Check the down_revision chains onto the current head (uv run alembic heads).
   • Watch for dropped columns/tables you didn't intend, server defaults, enum changes, and JSON/array types.
   • Name the revision file with the next sequential prefix to match the existing convention.