| name | database-migrations |
| description | How to create and use our alembic database migration tool. Use when making changes to models.py. |
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.
Alembic depends on having a valid DATABASE_URL set (the alembic env reads it from the environment). The username should be inspect_admin. The password is generated automatically via RDS IAM.
Get the admin URL from the stack's Pulumi output database_url_admin:
export DATABASE_URL=$(AWS_PROFILE=staging pulumi stack output database_url_admin -s <stack>)
(This is the same URL scripts/dev/generate-env.py <stack> --api writes as HAWK_API_DATABASE_URL.) Keep AWS_PROFILE=staging set for RDS IAM auth and Pulumi.
Run alembic from hawk/core/db (where the alembic config lives) — you don't need to pass it the path to alembic.ini.
To create a new migration, run:
alembic revision --autogenerate -m "description of changes"
Run ruff check --fix && ruff format to silence any formatting issues in the generated migration file.
You may need to ensure the DB is up to date before generating a new migration. Run:
alembic upgrade head
If we want to regenerate a migration file (in a branch we're working on after making schema changes since the last migration), we can delete the previous migration file and run the revision command again.
- Run
alembic downgrade -1 to revert the last migration.
- Delete the migration file from the versions/ directory.
- Run
alembic upgrade head to ensure the DB is up to date.
- Run the revision command again to generate a new migration file.
Verification
Run the tests in tests/core/db/test_alembic_migrations.py
