中国 帮助

数据库迁移

这一页解决一件事:给应用加表、加列、建索引、补数据时,脚本放哪、怎么打包、什么时候被执行、写错了怎么救。 一句话结论:脚本放插件的 migrations/,随应用包走,安装 / 升级时自动按文件名顺序执行; 平台不让你手工执行 SQL,也

数据库迁移
封面

> 本文整理自平台文档 docs/wujies/1.x/plugin-dev/advanced/migrations.mdx,用于站点内容演示。

(https://console.wujies.cn/remote-apps/cms-assets/doc-6b19a6239745-cover.svg)

这一页解决一件事:给应用加表、加列、建索引、补数据时,脚本放哪、怎么打包、什么时候被执行、写错了怎么救。

一句话结论:脚本放插件的 migrations/,随应用包走,安装 / 升级时自动按文件名顺序执行; 平台不让你手工执行 SQL,也不让插件代码自己建表。

# 在插件仓库根目录运行(路径:wujies/wujies-plugins/)
# 本机已有 keys/private.pem 时会自动用它签名 —— 宿主是 enforce,不签名等于白打一个包
pwsh -File package.ps1 -Plugin wujies-hello

不想动 app.json、只想额外塞一个修数据脚本时,用 -MigrationPath 指向它 (package.ps1 的 .EXAMPLE 里有原样可抄的命令,四种情况的表格见 [打包与产物](/docs/wujies/1.x/package/build))。

服务器上唯一知道"这个应用有哪些表"的地方,就是这些脚本里的 CREATE TABLE —— 所以建表语句必须进包。

图床原本是宿主编译期模块,5 张表建在平台初始化 SQL 里。改成插件应用之后, 客户那台只导入平台 SQL 的部署装上它就是所有页面报表不存在; 而且"彻底删除"时平台也无从知道该删哪些表。

所以建表脚本有两个身份:① 安装时建表;② 卸载时被平台读出来当删表清单。

执行链路

环节谁做说明
打包package.ps1默认取插件目录的 migrations/*.sql;-MigrationPath 可指定目录或单个文件
落位AppPackageDeployService解到 <pluginDir>/migrations/<appCode>/(落位前先清空该目录,见下)
执行AppMigrationService.applyPending扫描该目录 → 按文件名排序 → 逐个执行
记账app_schema_history键 (app_code, script),含 checksum / success / execution_ms
删表依据AppMigrationService.declaredTables从脚本里解析 CREATE TABLE 的表名,供"彻底删除"用

安装 / 升级的完整顺序(PluginAppInstaller):

产物落位  →  执行迁移脚本  →  加载新插件代码  →  同步菜单与授权

这个顺序是刻意做出来的:AppPackageDeployService.deploy(versionId, false) 只落位, 加载交给排在迁移之后的 assertBackendLoaded。所以插件在启动时机直接读新加的列是安全的。

控制台「部署」按钮走的是单参版本(落位即加载),它不跑迁移脚本 —— 只改表结构、不改代码时才用它。

脚本放哪、怎么命名

wujies/wujies-plugins/wujies-<app>/migrations/
  01-create-<app>-tables.sql         建表,纯 DDL(CREATE TABLE IF NOT EXISTS)
  0N-create-<app>-seed-data.sql      示例 / 必需基础数据(INSERT IGNORE + 显式主键)
  0N-create-<app>-dictionaries.sql   字典(MAX(dict_id)+N + WHERE NOT EXISTS)
  0N-create-<app>-website-config.sql 站点配置(MAX(config_id)+N + WHERE NOT EXISTS)
  • 文件名排序即执行顺序,所以必须有 01- / 02- 这样的数字前缀;
  • 编号只表示顺序,取下一个空号,别为了整齐重排既有脚本;
  • .sql 必须是该目录的顶层文件:打包只扫顶层,子目录里的脚本会被告警跳过;
  • 脚本以 UTF-8 读取(AppMigrationService.read 显式用 StandardCharsets.UTF_8)。

范例应用 wujies-hello 就是这四个文件的最小样本: 01-create-hello-tables.sql(一张表:业务列 + tenant_id + BaseEntity 的公共列 + del_flag)、 02-create-hello-seed-data.sql(两条示例数据)、 03-create-hello-website-config.sql(sys_config,config_category = 'hello')。 字典与站点配置的取值策略、生成工具见 [种子数据与站点配置](/docs/wujies/1.x/plugin-dev/advanced/seed-data)。

本页只讲迁移,但新表往往要配实体与 Mapper。别去找 *-api 契约模块 —— 平台里没有这个模块(wujies-modules/*-api 数量为 0)。 实体 / BO / VO / Mapper 接口 与 Mapper XML / Service / controller 全在 wujies-plugins/wujies-<app>/src/ 下,例如 wujies-gallery/src/main/resources/mapper/gallery/GalleryImageMapper.xml。 XML 由 PluginMapperRegistrar 在插件加载时动态注册,不是靠 mapperLocations 扫出来的。

四条硬规矩 + 一条表结构约束

这五条都能在 AppMigrationService 的类注释里找到完整推导。

### 1. 只做 up,不回滚

app.json 的 migrations(含 down)是预留字段,当前不参与执行。 要回退表结构,请自己写一个"反向"的新迁移脚本,当作一次正常变更发布。

### 2. 脚本必须幂等

MySQL 的 DDL 是隐式提交的,AppMigrationService 刻意不声明事务 —— 包一个大事务只会让人误以为失败能整体回滚。重试时已成功的会跳过, 失败的那个必须能重跑。

CREATE TABLE IF NOT EXISTS `hello_item` (
    id          bigint       NOT NULL AUTO_INCREMENT COMMENT '主键',
    name        varchar(64)  NOT NULL COMMENT '名称',
    remark      varchar(255) DEFAULT NULL COMMENT '备注',
    create_dept bigint       DEFAULT NULL COMMENT '创建部门',
    create_by   bigint       DEFAULT NULL COMMENT '创建者',
    create_time datetime     DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    update_by   bigint       DEFAULT NULL COMMENT '更新者',
    update_time datetime     DEFAULT NULL COMMENT '更新时间',
    tenant_id   varchar(20)  DEFAULT '000000' COMMENT '租户编号',
    del_flag    int          DEFAULT 0 COMMENT '删除标志',
    PRIMARY KEY (id),
    -- `KEY` 这种行内索引写法 MySQL 与沙箱的 H2 (MODE=MySQL) 都认
    KEY idx_hello_item_tenant (tenant_id)
);

失败时会写一条 success='0' 的记录并中断安装;人工处理后重试, 已成功的脚本会被跳过、失败的那条(脚本多半已修正)复用同一行重跑。

加列前要用 information_schema 判断,再动态执行。

### 3. 已执行过的脚本内容不能改

账本判据是 (app_code, script),同一个 script 名再来时比对 checksum, 不一致直接报错拒绝执行:

迁移脚本 <name> 的内容已被修改(摘要与首次执行时不一致),
为避免同一脚本产生两种结果,拒绝执行。请改用新的脚本名。

要变更就新增一个脚本。这是刻意的保护,不要绕过它: 01 让全新安装走到某个状态,02 让存量部署补齐到同一状态。

工作区是 CRLF、Linux 上是 LF,语义相同但摘要不同。 AppMigrationService.checksumMatches 同时认 LF 归一化摘要与 CRLF 摘要 (记账统一存 LF 归一化那份),真正的改动照旧拒绝。

*

本文导览

(https://console.wujies.cn/remote-apps/cms-assets/doc-6b19a6239745-guide.svg)

章节导览
THE END

喜欢就支持以下吧

评论区需要浏览器启用 JavaScript 才能加载。

回到内容