Managing Database Schema Migrations in Production with Flyway and Liquibase

Flyway and Liquibase version-control database schema changes the same way Git versions code — each migration is a numbered, immutable script that runs once and is recorded in a migrations table.

How Flyway works

• Flyway scans classpath:db/migration for files named V1__description.sql, V2__description.sql; it runs each unexecuted migration in order and records the checksum in the flyway_schema_history table
• On application startup (with Spring Boot auto-configuration), Flyway runs automatically before the application accepts traffic — which means the database is always at the schema version the application expects

The production migration risk

• The real danger is the window during a rolling deployment when old and new application versions are running simultaneously with the new schema — if V2 adds a NOT NULL column, the old version's INSERT statements fail because they don't include the new column
• Solution: the expand-contract pattern: V2 adds the column as nullable (old version's INSERTs work, new version writes null or the value); V3 (next release) fills in nulls and adds the NOT NULL constraint

Running migrations separately from the application

• For large tables, a migration that adds an index or rewrites rows can take minutes — running it during application startup blocks Spring Boot's initialization for those minutes, causing health check failures and deployment rollbacks
• Run migrations as a pre-deployment Kubernetes Job (Flyway's flyway migrate command) before deploying the new application version; the application starts with the schema already updated

Flyway vs Liquibase

• Flyway uses SQL or Java migration scripts — simple, explicit, and familiar to anyone who knows SQL; immutable after execution
• Liquibase uses XML/YAML/JSON changelogs — more database-agnostic (can generate SQL for different dialects), supports rollback scripts, and provides more granular change tracking; more configuration than Flyway