Skip to content

[fix] make V181 migration idempotent and self-repair flyway history - #4326

Merged
Aias00 merged 3 commits into
apache:masterfrom
orangeCatDeveloper:fix/v181-migration-idempotent
Aug 18, 2026
Merged

[fix] make V181 migration idempotent and self-repair flyway history#4326
Aias00 merged 3 commits into
apache:masterfrom
orangeCatDeveloper:fix/v181-migration-idempotent

Conversation

@orangeCatDeveloper

@orangeCatDeveloper orangeCatDeveloper commented Aug 17, 2026

Copy link
Copy Markdown
Contributor

Fixes #4325

On a fresh MySQL/PostgreSQL database the manager can lock itself out: the first boot fails halfway through migration V181, and every boot after that refuses to start — until someone hand-deletes a row from flyway_schema_history.

Root cause: two schema managers run at startup, Hibernate (ddl-auto) first and Flyway second. Hibernate creates hzb_sop_schedule from the entity, so V181's bare CREATE TABLE collides. Flyway records that failure in its history table, and validation then rejects every subsequent start:

FlywayValidateException: Validate failed: Migrations have failed validation
Detected failed migration to version 181 (update column)

The fix has two halves. The scripts become idempotent (CREATE TABLE IF NOT EXISTS / CREATE INDEX IF NOT EXISTS in both mysql and postgresql variants), so racing Hibernate no longer fails the migration. And for instances already locked out, FlywayConfiguration catches this one validation failure ("failed migration"), runs flyway.repair() and retries once — other validation errors (e.g. checksum mismatch) still propagate, since those need a human decision.

FlywayConfigurationTest pins both behaviors with mocks (repair + retry ordering; checksum errors rethrown without repair).

Verified against real MySQL 8 and PostgreSQL 15 (Hibernate-created table first, then Flyway with production baseline settings):

before: 1st boot  V181 CREATE TABLE collides -> failure recorded
        2nd boot  FlywayValidateException: Detected failed migration to version 181  (locked out forever)

after:  fresh install with pre-existing table -> migrate succeeds
        already-broken history                -> repair + retry succeeds, instance starts

@orangeCatDeveloper
orangeCatDeveloper force-pushed the fix/v181-migration-idempotent branch 2 times, most recently from 799aa74 to 811a2c0 Compare August 17, 2026 08:36
Hibernate ddl-auto creates hzb_sop_schedule before Flyway runs, so the
bare CREATE TABLE in V181 fails and the recorded failure blocks every
later start until the history row is deleted by hand. Make the scripts
idempotent and auto-repair the history for that one failure mode.
@orangeCatDeveloper
orangeCatDeveloper force-pushed the fix/v181-migration-idempotent branch from 811a2c0 to b013898 Compare August 17, 2026 11:43

@Aias00 Aias00 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

评审结论:APPROVE

修复启动自锁的 Flyway 自修复方案,两部分互补且测试到位。

修复点确认:

  1. 脚本幂等化:MySQL 与 PostgreSQL 的 V181 均改为 CREATE TABLE IF NOT EXISTS / CREATE INDEX IF NOT EXISTS,消除 Hibernate(ddl-auto)先建表、Flyway 后跑 V181 导致的 CREATE TABLE 冲突。
  2. 启动自愈delayedFlywayInitializer 捕获 FlywayValidateException——消息含 "failed migration" 时执行 flyway.repair() + 仅重试一次 migrate();其余校验错误(如 checksum mismatch)仍直接抛出交由人工处理。仅一次重试,无无限循环风险。

测试: FlywayConfigurationTest 用 mock 钉死两种路径——失败迁移触发 migrate→repair→migrate 顺序、checksum mismatch 不 repair 直接重抛。

非阻塞说明:

  • 靠异常 message 文本匹配 "failed migration" 属经验性做法;若 Flyway 未来改文案或本地化会失效。但测试已钉死当前确切文案,且兜底策略(不匹配就重抛)是安全的,可接受。

无阻塞问题,批准。

@Aias00
Aias00 merged commit 67c861a into apache:master Aug 18, 2026
5 checks passed
@orangeCatDeveloper
orangeCatDeveloper deleted the fix/v181-migration-idempotent branch August 18, 2026 06:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG] manager cannot start again after V181 migration fails (flyway records failed migration)

2 participants