0003 ent 建模,Atlas 生成迁移,goose 执行
- 状态:已接受(2026-10-23)
- 相关:设计文档 04 §2.3、§5;03 §7
背景
需同时支持 SQLite / MySQL / MariaDB / PostgreSQL;BS 的问题根源之一是数据库没有约束、迁移靠运行时探测。
决策
- 数据模型写在
ent/schema,go generate ./ent生成代码(用entc程序化生成,避免 ent CLI 的依赖冲突)。 - 迁移文件由
internal/tools/migdiff(ent + Atlas diff,goose 格式)按方言生成到migrations/{sqlite,mysql,postgres}/,提交进仓库、人工审阅。 - 运行时用 goose 执行内嵌的迁移:PostgreSQL 用会话锁、MySQL 用表锁防并发迁移;SQLite 迁移前自动
VACUUM INTO快照到data/backups/。 - 启动时自动迁移;绝不在请求路径上迁移。
- 所有时间列在 MySQL 上使用
DATETIME(6)(ent/schema/fields.go的datetimeType):ent 默认的TIMESTAMP在 2038 年溢出且受会话时区影响;驱动始终以 UTC 读写。(2026-10-23 代码审查补充)
影响
- SQLite 迁移可在本地用内存库生成;MySQL / PostgreSQL 需要一次性开发库,CI 用服务容器生成并做漂移检查(
git diff --exit-code migrations/)。 - M0 的 MySQL / PostgreSQL 初始迁移为手写,由 CI 漂移检查验证。