Database migrations

This document describes how to manage Alembic migrations in Crisis-Monitor.

Creating migrations

Generate and apply revisions when the models change:

flask --app app:create_app db migrate -m "Describe change"
flask --app app:create_app db upgrade

The historical chain starts at revision 0037 and assumes the pre-0037 schema already exists. CI therefore compiles every revision and renders the complete upgrade graph, verifies the single 0081 head and reads the complete history. It does not pretend that a fresh empty database or offline SQL render is a valid deployment target: historical data migrations require an existing schema and an online connection.

Run the manual check-migrations hook only against a development database that is already upgraded to the current head:

MIGRATION_CHECK_DATABASE_URL=postgresql://user:password@localhost/crisis_dev \
  pre-commit run check-migrations --hook-stage manual

The command fails when Alembic cannot compare the schema or when it would generate a new revision. It also refuses to run without MIGRATION_CHECK_DATABASE_URL or DATABASE_URL, so an ignored, stale local SQLite file cannot be mistaken for migration drift.

Squashing old migrations

The repository needs an owner-approved baseline migration before clean-database bootstrap can become a blocking CI gate. Do not delete, squash or rewrite the current migration history during ordinary feature or cleanup work: that change requires a verified production snapshot, restore rehearsal and a coordinated deployment plan.