4. 迁移失败常见原因：SQL语法错误、约束冲突、环境差异、资源不足、死锁与超时

Flyway 迁移脚本在异步任务中执行时，失败原因通常集中在五个维度。理解这些失败模式是设计恢复与重试策略的前提。下面逐一分析每种原因的特征、典型场景与识别方法。

4.1 SQL 语法错误

语法错误是最直接、最容易在开发阶段发现的失败类型，但在异步批量执行中仍可能因以下原因漏网：

• 数据库方言差异：开发环境使用 H2，生产环境使用 MySQL 8.0，某些函数（如 GROUP_CONCAT 与 STRING_AGG）语法不兼容。
• 保留字冲突：新增列名使用了数据库版本升级后新引入的保留字（如 RANK、LEAD）。
• 多语句分隔符：在同一个迁移脚本中混用 ; 与 GO（SQL Server 习惯），导致解析器提前截断。

Migration V2__add_user_role.sql failed!
SQL State  : 42000
Error Code : 1064
Message    : You have an error in your SQL syntax;
             check the manual that corresponds to your MySQL server version
             for the right syntax to use near 'RANK VARCHAR(50)' at line 1

4.2 约束冲突

约束冲突通常发生在数据迁移或表结构变更阶段，表现为违反主键、唯一索引、外键或检查约束。

4.3 环境差异

环境差异是异步迁移中最隐蔽的失败原因。开发、测试、预发、生产四个环境的配置参数、字符集、时区、存储引擎可能不一致。

• 字符集不匹配：开发库使用 utf8mb4，生产库使用 latin1，导致 VARCHAR 列插入 4 字节 emoji 时截断报错。
• SQL_MODE 差异：生产环境开启了 STRICT_TRANS_TABLES，开发环境未开启，导致 '' 插入 INT 列时报错。
• 存储引擎不同：开发使用 InnoDB，生产某表为 MyISAM，导致外键约束语句执行失败。
• 权限不足：迁移账号在预发环境有 ALTER 权限，在生产环境缺少 CREATE TEMPORARY TABLES 权限。

4.4 资源不足

资源不足导致的迁移失败在异步批量任务中尤为常见，因为多个迁移任务可能同时竞争数据库连接、磁盘 I/O 或内存。

4.5 死锁与超时

死锁与超时是并发迁移场景下的典型失败模式。当多个异步任务同时操作同一张表或同一行记录时，数据库锁机制可能引发冲突。

• 死锁（Deadlock）：两个事务互相等待对方释放锁，数据库检测到后自动回滚其中一个事务。错误码：1213 (MySQL)、1205 (SQL Server)。
• 锁等待超时（Lock Wait Timeout）：事务等待获取锁的时间超过 innodb_lock_wait_timeout（默认 50 秒）。错误码：1205 (MySQL)。
• 语句超时（Statement Timeout）：单个 SQL 语句执行时间超过 max_execution_time 或 JDBC 驱动设置的 queryTimeout。

-- MySQL 查看最近死锁日志
SHOW ENGINE INNODB STATUS\G

-- 在应用层捕获死锁错误并重试（最多 3 次，间隔指数退避）
try {
    flyway.migrate();
} catch (FlywayException e) {
    if (e.getMessage().contains("Deadlock")) {
        // 指数退避重试逻辑
        retryWithBackoff(3, 1000);
    } else {
        throw e;
    }
}

4.6 失败原因与重试策略对照

根据失败原因的可恢复性，可以将它们分为“不可重试”与“可重试”两类，并制定对应的处理策略。