database-migrations

name	database-migrations
description	Use when creating alembic migrations, applying migrations to remote environments, or recovering from schema drift. Triggers on changes to models.py, "run migration", "schema drift", "alembic", "database error in batch jobs".

Instructions

Do not write out alembic migrations yourself. Use the alembic tool to generate and apply migrations. You do not need to give alembic the path to alembic.ini. Do not manually drop any tables or columns in the DB. Always use alembic migrations to make schema changes.

Key Paths

• Models: hawk/core/db/models.py
• Migrations: hawk/core/db/alembic/versions/
• Alembic config: hawk/core/db/alembic/
• Tests: tests/core/db/test_alembic_migrations.py

Creating Migrations

# 1. Update model in hawk/core/db/models.py
# 2. Generate migration (creates file in hawk/core/db/alembic/versions/)
alembic revision --autogenerate -m "description of changes"
# 3. Format
ruff check --fix && ruff format
# 4. Review the generated file — autogenerate isn't perfect:
#    - Reorder columns so Base fields (pk, created_at, updated_at) come first
#    - Verify index names and constraints
#    - Ensure downgrade() is reversible

You may need to ensure the DB is up to date before generating a new migration. Run alembic upgrade head.

If you need to regenerate a migration (after making model changes since the last migration):

1. Run to revert the last migration.