Java.DBMigrationTools.How does Flyway deal with checksum mismatches?

Flyway detects checksum mismatches during validation and fails migration to prevent schema drift.
A mismatch means an already-applied migration file was changed.

Key phrase:

“Checksum mismatches indicate a violation of migration immutability.”

How Flyway detects a checksum mismatch

Flyway stores, for each applied migration, in flyway_schema_history:

• version
• description
• checksum
• success

When you run flyway migrate (with validateOnMigrate=true, default):

1. Flyway recalculates the checksum of local migration files
2. Compares it to the stored checksum
3. If different → validation fails

Typical error:

Validate failed: Migration checksum mismatch for migration V3__add_index.sql

Why checksums change (important distinction)

🟡 Harmless causes

• Whitespace changes
• Line endings (CRLF ↔ LF)
• Comments
• SQL formatting

🔴 Dangerous causes

• Changed SQL logic
• Modified DDL
• Changed data migration
• Reordered statements

Flyway cannot tell the difference — it only sees the checksum.

---

What Flyway does when a mismatch occurs

By default:

• ❌ Migration is aborted
• ❌ No new migrations are applied
• ❌ Startup fails (in Spring Boot)

This is intentional and correct behavior.

Interview phrase:

“Flyway fails fast to prevent silent divergence.”

Correct ways to handle checksum mismatches

✅ Option 1: Restore the original migration (BEST)

If the migration was changed accidentally:

• Revert the file to its original state
• Re-run migrate

This preserves immutability.

---

✅ Option 2: Create a new migration (MOST COMMON)

If the change was intentional:

• Undo the modification
• Add a new migration:

V4__fix_index_definition.sql

This is the recommended production approach.

⚠️ Option 3: flyway repair (ONLY in safe cases)

Use repair only if:

• The change is formatting-only
• No logical behavior changed
• You are 100% sure the DB state is correct

What repair does:

• Updates stored checksum to match the file
• Makes validation pass

Interview-safe wording:

“Repair is acceptable only for non-functional changes.”

What NOT to do (big red flags)

❌ Disable validation:

flyway.validateOnMigrate=false

❌ Edit flyway_schema_history manually
❌ Ignore the error and push to prod
❌ Use repair to hide real schema problems

These answers fail interviews immediately.

Repeatable migrations: special case

For R__ migrations:

• Checksum changes are expected
• Flyway automatically re-runs them
• No failure occurs

That’s why:

• Repeatables are for regeneratable objects
• Versioned migrations must be immutable

Typical production incident (real-life)

“Someone reformatted an old migration, CI passed locally, but prod failed on startup.”

Correct response:

1. Identify the change
2. If formatting-only → repair
3. If logic → revert + new migration
4. Re-run pipeline

Interview-ready answer (perfect)

Short answer (2–3 sentences):

“Flyway detects checksum mismatches during validation by comparing applied migration checksums with local files and aborts migration if they differ. This protects against modifying applied migrations and prevents schema drift. The correct fix is usually to restore the original migration or create a new one; repair should be used only for non-functional changes.”

That answer is senior-level and safe.