数据库自动化版本迁移

李国平 2025/2/7 DB

注意：

Mysql版本必须是 5.7/8.0，低于这些版本请自行升级该版本。
现有生产中的服务不方便升级数据库版本参见 “一、nacos 配置中心相关参数配置” 将 enabled 设置 false，或不用管可以不加配置参数直接忽略。

# 一、nacos 配置中心相关参数配置

1、ith-service-datasource-{active}.yaml 新增如下配置

spring:
  flyway:
    enabled: true
    table: ith_schema_history
    baseline-on-migrate: true
    clean-disabled: true

# 二、历史脚本版本记录表

该表不存在会自动创建历史脚本版本记录表

表结构说明介绍：

CREATE TABLE `ith_schema_history` (
  `installed_rank` int NOT NULL COMMENT '主键',
  `version` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT '版本号',
  `description` varchar(200) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT '描述',
  `type` varchar(20) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT '脚本类型: SQL',
  `script` varchar(1000) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT '脚本文件',
  `checksum` int DEFAULT NULL COMMENT '脚本内容哈希值',
  `installed_by` varchar(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT '执行者',
  `installed_on` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '执行时间',
  `execution_time` int NOT NULL COMMENT '执行耗时 ms',
  `success` tinyint(1) NOT NULL COMMENT '是否成功 1是 0否',
  PRIMARY KEY (`installed_rank`),
  KEY `ith_schema_history_s_idx` (`success`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='迁移脚本版本号历史记录表'

注意：执行SQL脚本版本若存在缺陷，系统自动执行迁移升级时会输出异常信息提醒并且启动失败，同时ith_schema_history会记录哪个版本脚本文件执行失败 success=0，当你修复该脚本版本再次构建前请先再ith_schema_history表中删除 success=0 的记录,SQL如下:

DELETE FROM ith_schema_history WHERE success = 0

# 三、脚本文件命名规则

一个完整的脚本名称由五部分组成：前缀 + 版本 + 分隔符 + 描述 + 文件后缀。

前缀：V表示版本迁移，版本号必须唯一，会计算校验和，执行过的文件不允许修改，按版本顺序执行，一个脚本只会执行一次；

R表示可重复迁移，其没有版本，不是只运行一次，而是每次程序启动，校验发生修改时，就会执行，R始终是在V执行完成后再执行。

版本号：任意的数字版本均可，可以是一个完整的数字或者用点符号分割的数字，版本之间从左到右进行比较大小，遇到点符号进行分割，以0开头的数字会自动移除前面的0后比较大小，如下均是合法的版本：

1
001
6.3
1.2.3.4
2024.07.30
20240730

分割符：两个下划线（__）作为分隔符，分割版本和描述。

描述：下划线或者空格分割单词即可。实际短横线分割单词也可以，理论上只要不和分割符冲突即可。

文件后缀：默认是 .sql

要求按如下格式均是合法的脚本名称：

V8.0.0__init.sql

V8.5.6__create.sql

V8.6.0__add_new_table.sql

R__add_new_table.sql

脚本存放位置：system-xjar\src\main\resources\db\migration 目录下

# 四、占位符变量使用

主要用于占位符替换功能，可将脚本版本文件定义的占位符表达式变量进行替换。

再 V8.6.0__init.sql 添加占位符表达式变量：

UPDATE ${orderService}.order_list SET xxx=xxx

变量和值定义：

方式1 - 通过启动参数定义

  java -jar -Dfile.encoding=UTF-8 -Xms2048M -Xmx2048M myapp.jar \
  --spring.flyway.placeholders.orderService=ith-service-order-dev\
  --spring.flyway.placeholders.anotherPlaceholder=anotherValue

方式2 - 通过参见一、nacos 配置中心相关参数配置新增配置属性

spring:
  flyway:
    enabled: true
    table: ith_schema_history
    baseline-on-migrate: true
    clean-disabled: true
    # 定义占位符表达式变量和值
    placeholders:
      orderService: ith-service-order-dev
      anotherPlaceholder: anotherValue

# 可重复执行脚本

清空数据脚本存放位置:

db/repeatable/R__truncate_data.sql

├── resources           # starter预配置通用组件
│   ├── db/migration    # 存放版本升级SQL脚本
│   ├── db/repeatable   # 存放可重复执行SQL脚本

首次执行：如果可重复脚本从未执行过，它会在首次迁移时被应用。
内容变更触发执行：如果可重复脚本的内容发生变化（即校验和发生变化），Flyway 会在下一次迁移时重新执行该脚本。
未变更时不执行：如果可重复脚本的内容未发生变化，则不会重复执行。

# yaml 配置

spring:
  flyway:
    locations:
    - classpath:db/migration
    # 不需要执行清空脚本环境 移除该配置
    - classpath:db/repeatable

# 云仓一键升级与数据初始化

产品发版：

打开版本控制管理 /产品版本管理没有产品信息则点击新建
操作栏点击发版填写版本号、更新日志说明、上传安装包提交

项目一键升级：

打开版本控制管理 /项目版本管理没有项目信息则点击新建
操作栏点击更多选择一键升级，再升级页面选择产品版本信息填入服务器运维端口信息和seel脚本点击确定就会自动同步产品版本并更新项目服务程序
一键升级支持历史运维端口和脚本信息可编辑修改或直接点击确定自动升级

项目一键数据初始化：

打开版本控制管理 /项目版本管理没有项目信息则点击`新建
操作栏点击更多选择一键初始化，再初始化页面上传你的数据脚本
勾选你上传的数据脚本点击右上角第一个一键初始化，系统自动上传项目服务端进行数据迁移同步并返回脚本执行状态信息。

# 其他

配置参数

以下是 Flyway 的常见配置参数及其说明，以表格形式列出：

配置参数	默认值	描述	Spring Boot 配置项
`enabled`	`true`	是否启用 Flyway。如果设置为 `false`，Flyway 将不会执行任何操作。	`spring.flyway.enabled`
`baselineVersion`	`1`	基线版本号，用于标记现有模式的版本。	`spring.flyway.baseline-version`
`baselineDescription`	`<< Flyway Baseline >>`	基线描述，用于标记现有模式的描述。	`spring.flyway.baseline-description`
`baselineOnMigrate`	`false`	迁移非空 schema 时是否自动调用基线。如果设置为 `true`，则会自动执行基线。	`spring.flyway.baseline-on-migrate`
`cleanDisabled`	`false`	是否禁用数据库清理。在生产环境中建议禁用。	`spring.flyway.clean-disabled`
`cleanOnValidationError`	`false`	验证失败时是否自动清理数据库。	`spring.flyway.clean-on-validation-error`
`validateOnMigrate`	`true`	迁移时是否自动验证。	`spring.flyway.validate-on-migrate`
`locations`	`classpath:db/migration`	迁移脚本的位置，可以包含多个路径，用逗号分隔。	`spring.flyway.locations`
`encoding`	`UTF-8`	SQL 迁移脚本的编码格式。	`spring.flyway.encoding`
`table`	`flyway_schema_history`	Flyway 元数据表的名称。	`spring.flyway.table`
`sqlMigrationPrefix`	`V`	SQL 迁移脚本的文件名前缀。	`spring.flyway.sql-migration-prefix`
`sqlMigrationSuffixes`	`.sql`	SQL 迁移脚本的文件名后缀。	`spring.flyway.sql-migration-suffixes`
`sqlMigrationSeparator`	`__`	SQL 迁移脚本的文件名分隔符。	`spring.flyway.sql-migration-separator`
`placeholderReplacement`	`true`	是否替换 SQL 脚本中的占位符。	`spring.flyway.placeholder-replacement`
`placeholderPrefix`	`${`	占位符的前缀。	`spring.flyway.placeholder-prefix`
`placeholderSuffix`	`}`	占位符的后缀。	`spring.flyway.placeholder-suffix`
`placeholders.*`	-	自定义占位符及其值。例如 `placeholders.myPlaceholder=myValue`。	`spring.flyway.placeholders.*`
`lockRetryCount`	`50`	获取锁失败时的重试次数。	`spring.flyway.lock-retry-count`
`ignoreFutureMigrations`	`true`	是否忽略未来的迁移脚本。	`spring.flyway.ignore-future-migrations`
`group`	`false`	是否将所有待执行的迁移脚本放在同一个事务中。	`spring.flyway.group`

这些配置项可以通过 Spring Boot 的 application.properties 或 application.yml 文件进行设置，也可以通过命令行参数或 Java API 进行动态配置。

域名切换方案数据库云仓

Th技术开发白皮书

Choose mode