Files
lpt-be/roles/database-migration.md
T

2.0 KiB
Raw Blame History

数据库迁移

  • 功能:约束 Flyway 迁移脚本的写法,让数据库结构变更可追溯、可部署。
  • 何时用:新增或修改表结构、编写迁移脚本、调整索引、部署前核对历史数据时。

数据库迁移(Flyway Migration)

测试用 H2、部署用 MySQL:这几件事 H2 测不出来

迁移脚本在测试里跑的是 H2(MODE=MySQL),它与真实 MySQL 的差异会造成「测试全绿、部署起不来」:

  • 索引键长度上限:InnoDB 对索引键有 3072 字节硬上限(DYNAMIC 行格式),超了直接报 error 1071; utf8mb4 下 VARCHAR(n) 要按 4n 字节算,多列唯一键很容易越界。H2 不校验。 → 改动任何索引后跑 MigrationIndexKeyLengthTest(它直接读迁移文件复算键长)。
  • 整型显示宽度:TINYINT(1) 在 MySQL 8.0.17 起被标记弃用(MySQL 9.7 文档确认尚未移除,只是弃用)。 这里刻意保留 TINYINT(1):它正是 JDBC 把列映射成 Boolean 的惯用声明,换成裸 TINYINT 会让布尔字段的映射行为依赖连接参数。
  • 遇脏数据要响亮失败:V20261009_3(业务编号唯一约束)与 V20261009_5(计时列类型修正) 在历史数据不干净时会直接让启动失败。这是有意的——宁可失败也不静默跳过约束。部署前先按迁移注释里的核对 SQL 检查。

命名规则

  • 脚本格式:V{YYYYMMDD}_{序号}__{描述}.sql
  • 日期必须使用实际编写日期,不得使用过去的日期
  • 序号从 1 开始,同一天多个脚本递增
  • 描述使用下划线分隔的英文短语

核心原则

  • 不可变性:已执行的迁移脚本永远不得修改
  • 只增不减:数据库变更只能通过新增迁移脚本实现
  • 向后兼容:新脚本应兼容已有数据

操作规范

  • 删除表:创建新迁移脚本,使用 DROP TABLE IF EXISTS
  • 修改表结构:使用 ALTER TABLE 语句
  • 新增表:创建新迁移脚本,使用 CREATE TABLE