Flyway validation: detect a changed applied migration before another write

The ordinary path

After applying V1 through V3, the fixture counts three successful versioned history entries, reruns migrate and sees zero executed migrations, then calls validate without failure. The check is about history consistency, not business-row correctness. The receipt assertions separately prove that the column contract changed as expected.

A second test deliberately corrupts the recorded checksum for version 2 and expects FlywayValidateException. That is a controlled simulation of a history mismatch. It does not edit a committed migration file or show how an operator should repair a production history table. The versioned-file lesson establishes the files being compared.

Do not auto-repair uncertainty

A mismatch is a reason to stop and inspect the deployed file, prior release artifact and schema state. Rewriting history to silence validation can hide drift. A failed non-transactional DDL step needs a database-specific recovery procedure, a reviewed forward migration or a restore decision.

The fixture is isolated H2 and has no concurrent migrators. It does not show a process crash between SQL statements, target-database transaction semantics or deployment locks. The rollout matrix lists the untested states.

Checked source

migrationAt("3").migrate();
jdbc.update("update "flyway_schema_history" "
    + "set "checksum" = "checksum" + 1 where "version" = '2'");
assertThrows(FlywayValidateException.class,
    () -> migrationAt("3").validate());

Verification boundary

FlywayReceiptMigrationTest.changedRecordedChecksumFailsValidation. The excerpt is shortened or a labelled design sketch; the kit contains the checked tests.

Costs and limits

The test corrupts a checksum in an isolated H2 history table. It does not change a deployed SQL file, perform repair or prove crash recovery for DDL on another engine.

Common Mistakes

• Do not treat a green row-count check as migration-history validation.
• Do not change recorded checksums manually in a deployed database to clear an error.
• Do not assume every database rolls back DDL on migration failure.

Read next

Flyway SQL migrations: record ordered schema changes against a real database, Spring Boot and Flyway: choose who runs migrations before traffic starts, Spring schema rollout tests: check old and new writers at every phase, Spring Boot migrations: what a versioned runner must add to the SQL test.

Continue with checked Boot startup

Continue with Spring Boot migration history failure: stop context startup on a mismatch.