Alembic Downgrade vs. Metadata Database Restore for Failed Upgrades

Schema Recovery Strategies

When performing an Apache Airflow upgrade, the airflow db upgrade command applies incremental schema revisions via Alembic. If a migration fails mid-process, the metadata database may be left in an inconsistent state, necessitating a recovery action before the scheduler or webserver can be safely restarted.

Recovery Constraints

There are two primary documented paths for reverting a failed migration, each presenting different trade-offs regarding data integrity and operational continuity:

• Manual Alembic Downgrade: Using airflow db downgrade <revision> to revert specific schema changes. This is faster but may leave orphaned tables or partial data inserts that the migration script did not explicitly handle in its downgrade logic.
• Full Database Restore: Restoring the metadata database from a snapshot taken immediately prior to the upgrade. This ensures a clean state but results in the loss of any DAG runs or task instances created between the backup and the failure.

Given that Airflow lacks an automated rollback mechanism for failed migrations, the choice depends on whether schema purity or the preservation of recent task metadata is the priority.

Technical Questions

• In what scenarios does a manual Alembic downgrade fail to return the metadata database to a state compatible with the previous Airflow version?
• Is there a documented method to verify schema consistency after a downgrade without performing a full database restore?