Database Migrations — Flyway, Liquibase, Alembic

A migration script that applies a forward schema change — adding a table, column, constraint, or index. Runs when deploying new application versions.

"The up migration adds the user_preferences table with 5 columns and a foreign key to users — it runs on the first deployment of the v2.3 release."

A migration script that reverses a corresponding up migration — dropping tables, columns, or constraints — used to undo a failed deployment.

"After the failed deploy, we ran the down migration which dropped the broken column and restored the previous schema state, letting us roll back the application code safely."

A database table (flyway_schema_history in Flyway, alembic_version in Alembic) that records which migrations have been applied — their version, description, checksum, and execution time.

"The Flyway migration history table showed migration V15 had failed with a checksum mismatch — someone had edited the migration file after it had already run, which Flyway detects automatically."

A migration that runs every time its content changes — used for database views, stored procedures, and functions that should always reflect the latest version in source control.

"Our summary_view is managed as a repeatable Flyway migration prefixed with R__ — whenever we update the view definition, the migration reruns automatically on the next deployment."

A special migration that marks the current state of an existing database as the starting point for migration tracking, allowing Flyway/Liquibase to be introduced to databases that weren't managed from the start.

"We introduced Flyway to a 3-year-old database by creating a baseline migration representing the existing schema — all future migrations are tracked from that baseline version."

A situation where two developers create migrations with the same version number, or where a migration was skipped in one environment but applied in another — causing schema inconsistency.

"Both Alice and Bob created V45 migrations on separate branches — on merge, the conflict was caught by the version numbering convention. We renumbered one to V46 and updated the migration history."

A check performed by migration tools that verifies a migration's content hasn't changed after being applied — preventing silent inconsistencies between schema history and actual migration scripts.

"Flyway's checksum validation failed on deploy because a developer had fixed a typo in a migration comment after the migration had already run in staging — we had to repair the migration history entry."

The version number of the highest applied migration in a database — used to determine which pending migrations need to be applied to bring the schema to the expected state.

"Staging was at schema version V38, production at V36 — the deploy included migrations V37, V38, and the new V39, which were applied sequentially to bring production in sync."

A migration strategy that avoids dropping or renaming existing columns immediately — instead adding new columns and transitioning data gradually to support zero-downtime deployments with backward-compatible schema changes.

"For the column rename, we used a non-destructive migration: first add the new column, backfill data, update the application to write to both, verify, then drop the old column in a later migration."

Three widely used database migration tools: Flyway (SQL and Java, version-based), Liquibase (XML/YAML/JSON/SQL, changeset-based), and Alembic (Python/SQLAlchemy, script-based).

"We chose Flyway for its simplicity — SQL-first approach, no XML, and easy CI integration. Liquibase was preferred by the enterprise team for its XML changesets and rollback generation. Alembic is standard for Python/FastAPI services."