Flyway 脚本规范

Forge 使用 Flyway 管理数据库版本迁移。所有表结构变更和内置数据必须通过 Flyway 脚本提交，不允许只改实体或手动改库。

目录约定

目录	用途
forge-server/db/migration/	Flyway 版本化迁移脚本
forge-server/db/seed/required/	系统运行必需初始化数据
forge-server/db/seed/demo/	演示数据（默认不导入）
forge-server/db/seed/optional/	可选模块数据

命名规范

V<版本号>__<lower_snake_case_description>.sql

规则	示例
版本号单调递增	V1.0.1、V1.0.2、V1.1.0
描述用小写下划线	add_dashboard_version_table
基线版本	V1.0.0__baseline.sql（已存在，不可修改）
新版本必须大于 1.0.0	V1.0.1__add_user_avatar.sql

脚本编写规则

必须可重复执行

-- 建表用 IF NOT EXISTS
CREATE TABLE IF NOT EXISTS biz_order (
    id BIGINT NOT NULL COMMENT '主键',
    ...
);

-- 新增列前检查 information_schema
SET @col_exists = (
    SELECT COUNT(*) FROM information_schema.COLUMNS
    WHERE TABLE_SCHEMA = DATABASE()
      AND TABLE_NAME = 'sys_user'
      AND COLUMN_NAME = 'avatar'
);
SET @sql = IF(@col_exists = 0,
    'ALTER TABLE sys_user ADD COLUMN avatar VARCHAR(255) NULL COMMENT ''头像''',
    'SELECT 1');
PREPARE stmt FROM @sql;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;

INSERT 防重复

-- 内置数据必须用 NOT EXISTS 保护
INSERT INTO sys_dict_type (id, dict_name, dict_type, tenant_id)
SELECT NULL, '订单状态', 'biz_order_status', 1
WHERE NOT EXISTS (
    SELECT 1 FROM sys_dict_type WHERE dict_type = 'biz_order_status' AND tenant_id = 1
);

必须显式写列名

-- 正确
INSERT INTO sys_dict_data (dict_sort, dict_label, dict_value, dict_type, tenant_id)
VALUES (1, '待支付', '0', 'biz_order_status', 1);

-- 禁止
INSERT INTO sys_dict_data VALUES (1, '待支付', '0', 'biz_order_status', 1);

关键约束

• 业务内置数据 tenant_id 必须为 1，禁止写 0
• 已执行的脚本（进入 forge_schema_history）禁止修改
• 需要修正时新增下一个版本脚本
• 生产敏感数据、密码、Token 禁止提交到 SQL
• sys_resource、sys_role_resource 脚本必须做 NOT EXISTS 防重复

验证迁移

SELECT installed_rank, version, description, success
FROM forge_schema_history
ORDER BY installed_rank DESC;

启动执行

forge-admin-server 启动时自动执行 forge-server/db/migration 脚本。默认配置兼容不同启动目录：

filesystem:./db/migration,filesystem:../db/migration,filesystem:forge-server/db/migration

如果迁移未执行，检查环境变量 FORGE_FLYWAY_LOCATIONS 和 FORGE_FLYWAY_ENABLED 是否覆盖了默认配置。