Java.DBMigrationTools.What causes a checksum mismatch and how do you fix it?

Checksum mismatches happen when the migration tool detects that a migration it already recorded as “applied” is not byte-for-byte the same anymore.

That’s a feature: it protects you from silently changing production history.

What causes a checksum mismatch

Flyway

Flyway stores a checksum per migration in flyway_schema_history. A mismatch occurs when:

• someone edited an already-applied V…__*.sql (even whitespace/comments can matter)
• line endings changed (CRLF ↔ LF) or file encoding changed
• placeholders expanded differently than before (e.g., ${schema} changed)
• you upgraded Flyway and it recalculates checksum differently in some edge cases (rare, but possible)
• a build step rewrote files (formatters, templating, copy step)

Liquibase

Liquibase stores MD5 in DATABASECHANGELOG (MD5SUM). A mismatch occurs when:

• an applied changeset file was edited
• the changeset content changes via included files
• some property substitution results differ (depending on how you structure it)

Liquibase also has runOnChange and runAlways which change the expected behavior (but you should be intentional with them).

How to fix it (the right way)

1) First decide: was the change legitimate?

• If this is prod (or any shared env): assume editing applied migrations is not allowed.
• If this is only your local/dev and can be rebuilt: you can repair/reset.

2) Preferred fix: revert + create a new migration

Best practice: restore the original migration file exactly as applied, then add a new migration for the new change.

• Revert the modified file from git
• Create Vnext__fix_whatever.sql (Flyway) or a new changeset (Liquibase)

This keeps history immutable and audit-friendly.

3) If the DB history is wrong but the file is correct: “repair”

Use this only when you’re confident the DB schema matches reality and you just need to update recorded checksums.

Flyway

• flyway repair
  • updates checksums in flyway_schema_history
  • removes failed migration entries (depending on state)

Use when: you accidentally changed whitespace/comments, or you had a known safe rewrite and you want the metadata to match.

Liquibase

• liquibase clearCheckSums
  • clears stored checksums; next run recalculates

Use when: same idea—metadata mismatch, not schema mismatch.

4) For local/dev only: wipe and re-run

If the environment is disposable:

• drop schema / recreate DB
• run migrations cleanly

That’s often fastest and safest for dev.

What not to do

• Don’t manually edit flyway_schema_history / DATABASECHANGELOG unless you really know what you’re doing (and even then, prefer tool commands).
• Don’t “repair” in prod to hide an accidental modification of an applied migration. That masks a process problem.

Interview-ready phrasing (short)

“A checksum mismatch means an already-applied migration file changed after it was recorded in the schema history table. The correct fix is to treat migrations as immutable: revert the file and create a new migration for the new change. If it’s only a metadata mismatch and the schema is correct, use Flyway repair or Liquibase clearCheckSums; for disposable dev environments, rebuild the DB.”