spring-boot-demo/db-migrations-flyway-liquibase/docs/03-checksum-validation.md

3. Checksum validation: why editing an applied migration fails

← 2. Anatomy of a migration run · Index · Next: 4. Out-of-order migrations →

The most common way a migration tool earns its keep is by refusing to do something that would otherwise fail silently, weeks later, on a machine nobody's watching. This is the simplest version of that: someone "just tweaks" a migration file that has already run somewhere, instead of writing a new one.

FlywayChecksumMismatchTest starts a context against V1__init.sql, lets it apply cleanly, then edits that same file on disk — widening a varchar(50) to varchar(80) — and starts a second context against the same database. Flyway's default (spring.flyway.validate-on-migrate=true) compares every applied migration's recorded checksum against the file's current checksum before attempting to migrate anything else, and the second startup fails outright:

FlywayValidateException: Validate failed: Migrations have failed validation
Migration checksum mismatch for migration version 1
-> Applied to database : -712784830
-> Resolved locally    : 756220147
Either revert the changes to the migration, or run repair to update the schema history.

(quoted verbatim from docs/output/02-flyway-checksum-mismatch.txt)

That message is doing real work: it's telling you the checksum stored in flyway_schema_history for version 1 no longer matches the file Flyway just read off disk. Nothing about the schema is inconsistent yet — the failure happens before any SQL runs, which is the entire point. A team that lets this slide by running flyway repair out of habit is telling Flyway "the file changed on purpose, update your record" — which is right for a comment or formatting fix, and very wrong for "I need this table to actually have the new column now", which needs a new V3__... file, not a rewrite of V1.

What checksum validation is not

It is not a guarantee that the applied schema matches the current file. Flyway checks the file against what it already recorded, not against the live schema — if someone hand-edits the table after the fact, nothing here notices. It's a version-control safety net for the migration files themselves, not a schema-drift detector.

Going deeper

• spring.flyway.validate-on-migrate in the Spring Boot configuration reference (rel="nofollow") — true by default.
• Flyway's repair command (rel="nofollow") — what actually happens to flyway_schema_history when you run it, and why it's a deliberate, logged action rather than something to script into a startup hook.