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

The isolated failure

BootFlywayStartupTest first starts at version 3 in an isolated H2 database. It then changes the recorded checksum for V2 in that disposable history table and closes the context. A second Boot start against the same database throws before returning an application context. The test asserts failure; it does not suppress the mismatch or call repair.

The direct API fixture isolates the validation exception. This Boot fixture checks the additional boundary: the application context itself does not finish creation. A deployment platform should keep an instance out of traffic when startup fails, but that platform behavior is not exercised here.

Stop and inspect before repair

A checksum mismatch may mean an applied file changed, an artifact was built incorrectly or the history table was altered. Inspect the release artifact and actual schema before deciding on a forward migration or a database-specific recovery procedure. Editing the history row to make startup pass can hide incompatible state.

The test deliberately modifies a checksum, not a SQL file. It says nothing about incomplete DDL on engines that cannot roll back a failed migration. The test-scope boundary also means ReceiptApplication has no such startup gate yet.

Checked source

try (var context = start(url, 3)) {
    context.getBean(JdbcTemplate.class).update(
        "update "flyway_schema_history" set "checksum" = "checksum" + 1 where "version" = '2'");
}
assertThrows(RuntimeException.class, () -> start(url, 3));

Verification boundary

BootFlywayStartupTest.invalidHistoryPreventsTheNextBootStartup. The excerpt is shortened; the source kit contains the checked fixture.

Costs and limits

The mismatch is injected into H2 history. No applied SQL file is edited and no deployment orchestrator, target engine or recovery action is tested.

Common Mistakes

• Do not clear a checksum error by rewriting production history without investigation.
• Do not serve traffic from a context that failed startup.
• Do not treat a checksum check as proof that business rows are correct.

Read next

Spring Boot Flyway startup: apply versioned SQL before querying a receipt, Flyway validation: detect a changed applied migration before another write, Spring Boot migration tests: distinguish a test starter from a runtime rollout, Spring readiness: report an unavailable dependency without forcing liveness failure.