Documentation
¶
Overview ¶
Package migrate 提供「裸 SQL 脚本 + 清单」的建表/升级执行器。
形态约定(与既有消费方互通,不可改):
- 脚本清单**单层平铺**:install 与 upgrade 共用一份列表,按 Target 前缀选目录
- 幂等兜底:重复键/列/索引、建表「已存在」类错误一律跳过;多列 ALTER TABLE ... ADD a, ADD b 失败时自动拆成单列逐条执行(MySQL 的多列 ADD 是原子的, 直接跳过会漏掉真正需要新增的列;非 ADD 子句不连坐 ADD 条目,head 也入 守卫,#164)
已知局限:不支持 DELIMITER / 存储过程脚本(#104) ¶
SplitStatements 按「引号外分号切分」工作,没有 DELIMITER 状态机——MySQL 存储过程/触发器脚本(DELIMITER $$ ... END$$ DELIMITER ;)的过程体内分号 会被当作语句终止符逐条拆出,必然语法报错导致迁移中止。此类脚本请经专用 迁移通道;执行中命中 DELIMITER 指令时打 WARN 指明根因(否则消费方看到的 是过程体第一句的语法错误,不会指向切分器局限)。
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsIgnorableError ¶
IsIgnorableError 判断异常是否属于「重复执行可跳过」。
判定面两级(#96,对齐根包 IsBusyErr 的结构论证:驱动文案**不是契约**—— MySQL 驱动升级、PG 本地化 locale(lc_messages 非英语时错误文案整句变型)、 proxy/中间层改写都会动文案,且文本匹配双向危险:漏匹配让幂等错误中断 迁移,过宽匹配让致命错误被静默跳过、schema 缺东西而迁移「成功」):
- 类型化主判(isIgnorableTyped):MySQL 错误号(*mysql.MySQLError.Number: 1050/1060/1061/1062/1091)与 PG SQLSTATE(*pgconn.PgError.SQLState(): 42P07/42P01/42701/42710/23505)——码是协议层契约,不受文案漂移影响;
- 文案兜底(最后防线):下方英文子串表,仅覆盖类型化路径够不到的 驱动/方言(如 sqlite 的 "already exists")。表内容不是契约, 驱动改文案后只剩它时判定即退化——不要反向依赖它。
两级判据都不命中时按致命错误处理(不跳过、显式报错)。
func Run ¶
Run 依次执行 install 与 upgrade 全量脚本。
全量执行(而非记账只跑增量)是刻意的:脚本本身被设计成幂等 (CREATE TABLE IF NOT EXISTS / INSERT IGNORE 等),重复执行靠幂等 + 异常兜底保证安全。
Options.LockKey 非空时,全量执行在会话级咨询锁内串行化(多副本首启 DDL 互斥,见 Options.LockKey 文档)。
⚠️ 无 ctx 兼容入口(#177):等价于 RunContext(context.Background(), d, opts) ——DDL 不可取消、advisory lock 拿锁可无限阻塞。新代码请用 RunContext。
func RunContext ¶ added in v0.11.14
RunContext 与 Run 相同,但 ctx 贯穿全链路(#177):
- 每条语句经 d.WithContext(ctx).Exec 执行——ctx 取消/超时即中断, DDL 不再「一旦卡住只能杀进程」;
- LockKey 路径把 ctx 传入 RunWithAdvisoryLock——MySQL GET_LOCK(?, -1) 的无限阻塞拿锁可被 ctx 取消中断(未拿到锁的路径无锁可解)。
ctx 为 nil 时按 context.Background() 处理。
func SplitStatements ¶
SplitStatements 把 SQL 文件切成单条语句。
规则(与 Spring 复刻消费方 splitStatements 同规则):
- `--` 行注释、`/* */` 块注释被剥离(随语句一起丢弃)
- 单引号 / 双引号 / 反引号内的分号不切分(反斜杠转义引号可正确跳过)
- 以 `;` 结尾为一条语句;空语句丢弃
⚠️ 不支持 DELIMITER / 存储过程脚本(#104,见包文档「已知局限」): 没有 DELIMITER 状态机,过程体内的分号会被当作语句终止符逐条拆出。
Types ¶
type Options ¶
type Options struct {
// Target 目标标识(如 "mysql" / "postgre"),用于拼脚本目录 <Root>/<Target>/<script>。
Target string
// Install 安装脚本清单(按序全量执行)。
Install []string
// Upgrade 升级脚本清单(install 之后按序全量执行)。
Upgrade []string
// FS 脚本来源(embed.FS / os.DirFS / fstest.MapFS 均可)。
FS fs.FS
// Root 脚本根目录(FS 内的相对路径,如 "ddl")。
Root string
// LockKey 非空时,Run 把全量执行包进 gormx.RunWithAdvisoryLock 的
// 会话级咨询锁内(#98:多副本同时首启的 DDL 串行化组合口)。
//
// - 空 = 不加锁(缺省行为不变;单副本/开发环境);
// - 键为字符串,跨副本用**同一字符串**即互斥;建议口径取稳定业务
// 维度(如 db 名 + 表清单哈希)——每库一个键会在多服务共用库时
// 互锁,每 target/表一个键粒度又太细(本就该一起串行化的脚本
// 被拆成并行);
// - 内部经 FNV-1a 64 折成 int64 会话键(PG/MySQL 咨询锁键域),
// 同一字符串必得同一 int64;不同字符串碰撞概率 2^-64 量级;
// - 拿锁阻塞直到获得或 ctx 取消(#177:RunContext 传入的 ctx 可中断
// 无限阻塞的拿锁;旧 Run 入口用 Background,行为不变),拿锁失败/
// 执行失败都返回错误 = fail-closed:交给部署的重启策略重试,
// 比静默无锁执行安全(多副本并发 DDL 正是要防的事故形态);
// - 方言不支持会话级咨询锁(sqlite 等)显式返回
// gormx.ErrAdvisoryLockUnsupported——与 RunWithAdvisoryLock 的
// 方言策略对齐,不静默降级为无锁执行。
LockKey string
}
Options 是一次迁移执行的配置。