Appearance

数据库快速入门 ​

本文说明 ECShopX Java 如何通过 Flyway 管理增量 SQL 迁移，以及 bin/make-migration 脚本的标准用法。命令与配置以仓库 bin/make-migration 脚本及 application-local.properties 为准。

迁移目录 ​

全库迁移脚本统一放在：

text
ecshopx-bootstrap/src/main/resources/db/migration

文件命名遵循 Flyway 规范：VyyyyMMddHHmmss__description.sql。

默认行为 ​

ecshopx-bootstrap 中默认配置：

配置项默认值含义
spring.flyway.enabledfalse不在应用启动时自动执行迁移，避免本地误改库
spring.flyway.baseline-on-migratetrue已有库首次接入 Flyway 时从版本 0 建立基线
spring.flyway.baseline-version0基线版本号

执行记录写入 flyway_schema_history 表。baselineOnMigrate=true 可避免首次接入时重跑历史建库 SQL（如 docker/ecshopx.sql 已导入的库）。

典型流程：改表 → 生成 → Review → 迁移 ​

在 ecshopx-java 仓库根目录执行：

bash
cd ecshopx-java

# 1. 先在 domain 实体上声明新字段（见 mapper-access.md），再生成迁移
bin/make-migration add_xxx_index

# 2. Review 生成的 SQL（路径示例）
# ecshopx-bootstrap/src/main/resources/db/migration/VyyyyMMddHHmmss__add_xxx_index.sql

# 3. 人工确认：列类型、长度、NULL、默认值、注释、索引、列顺序

# 4. 手动执行迁移
bin/make-migration migrate
# 或指定 local profile（读取 application-local.properties 中的数据源）
bin/make-migration migrate --profile local

bin/make-migration 生成逻辑 ​

脚本对比当前数据库结构与 domain 注解推导的目标结构，生成增量 SQL：

输入来源
from schema连接 spring.datasource.* 指向的 MySQL，读取当前库结构
to schema扫描各 Bundle 的 domain 包，根据 @MpTable / @MpField / @MpId（及兼容的 @TableName / @TableField / @TableId）推导目标结构
输出生成从 from → to 的 ALTER TABLE / CREATE TABLE 等 SQL

生成后必须人工 review，原因包括：

  • MyBatis-Plus 注解无法完整表达列长度、精度、nullable、普通二级索引等全部元数据
  • 普通二级索引不会凭空生成（除非在 @MpTable.indexes 中声明）
  • 默认不会为库中存在但 domain 中不存在的表/列生成 DROP，除非传入 --allow-drop

常用参数 ​

bash
bin/make-migration --profile local add_order_extra_index
bin/make-migration --filter-expression '^items$' sync_items
bin/make-migration --changed-only add_order_extra_index
bin/make-migration --allow-drop sync_domain_schema
bin/make-migration --db-url "jdbc:mysql://127.0.0.1:3306/ecshopx" --db-user ecshopx --db-password ecshopx add_order_extra_index
bin/make-migration --empty manual_data_fix
参数说明
--profile <name>叠加读取 application-<name>.properties
--filter-expression <re>正则过滤表名
--changed-only仅对比 git diff 中变更的 domain 文件
--allow-drop允许生成 DROP COLUMN / DROP TABLE
--empty生成空白 SQL 模板
migrate调用 Flyway Maven 插件执行 migrate（非生成文件）
repair修复 flyway_schema_history 校验失败

migrate 子命令同样支持 --profile / --db-url / --db-user / --db-password。

与 domain 注解的协同 ​

  1. 在 ecshopx-<domain>/domain/ 修改或新增实体字段（@MpField 等）
  2. 运行 bin/make-migration <description> 生成 SQL
  3. Review 并修正 SQL 后提交到 db/migration
  4. 执行 bin/make-migration migrate 更新目标库
  5. 启动应用验证（spring.flyway.enabled=false，迁移与启动解耦）

相关章节 ​