Skip to content

feat(db): 支持 MySQL 8.4(双引擎数据库) - #53

Merged
IGNGserver merged 9 commits into
masterfrom
agent/mysql-dialect
Nov 15, 2026
Merged

IGNGserver merged 9 commits into
masterfrom
agent/mysql-dialect

Conversation

@IGNGserver

Copy link
Copy Markdown
Owner

做了什么

在保留 PostgreSQL 默认路径的前提下,为 TaskDock 增加 MySQL 8.4 支持:用户可以用 mysql:// 的 DATABASE_URL 或离散 MYSQL_* 变量选择引擎,MySQL 既可以是内置 Compose 服务,也可以是外部服务器。

没有复制第二套存储层,也没有换 ORM:PostgresStore/PostgresTreeStore 改名为 SqlStore/SqlTreeStore,接收 SqlDatabase 抽象,方言差异集中在 @devtodo/database。

关键设计

  • 方言层:$n 占位符按引擎翻译(MySQL 重排为 ?,支持参数复用)、剥离 ::type、ILIKE → LIKE、IS NOT DISTINCT FROM → <=>、保留字 rank/cursor 自动加引号。
  • 只有 4 处语句保留两份拼写(apps/api/src/sql-statements.ts):owner 快照、sync pull、目录分页、文件夹路径——它们依赖 JSON 聚合、MATERIALIZED 或递归 CTE。
  • RETURNING 同事务回查;sync_changes.seq 用 insertId + affectedRows 推导批内游标。
  • 部分唯一索引 → 生成列(IF(deleted_at IS NULL, 1, NULL) + 唯一键,NULL 不冲突),部分普通索引退化为全量索引。
  • MySQL 迁移从合并基线开始:migrations/mysql/0013_baseline.sql 等价 PostgreSQL 0001..0013;此后每个变更两边各一个同版本文件,测试保证版本与表集合一致。迁移 runner 在 MySQL 下用 GET_LOCK 串行、逐文件提交并拆分语句。
  • 通知降级:进程内在 COMMIT 后 fan-out;跨实例实时推送需要 Redis pub/sub 或轮询(DB_LISTEN_ENABLED 对 MySQL 恒为 false)。

与 PostgreSQL 的差异(已写入 ADR 0005 与文档)

能力 PostgreSQL MySQL
跨实例实时推送 LISTEN/NOTIFY 进程内通知 / Redis / 轮询
搜索 pg_trgm GIN LIKE '%term%' 扫描
语句级超时 读写都覆盖 仅 SELECT
迁移原子性 整个迁移集一个事务 DDL 隐式提交,逐文件记录

另外:MySQL 基线里子外键全部级联删除(删 Owner 一步完成),省略了 refresh_sessions(owner_id, replaced_by_id) 自引用外键(复合键含 NOT NULL 列时无法 SET NULL)。不做 PostgreSQL → MySQL 存量数据搬迁,也不支持 MariaDB。

验证矩阵(本地真实数据库)

门禁 PostgreSQL 18.6 MySQL 8.4.13
pnpm typecheck / lint / format:check / build ✅ ✅
单元测试(294 项) ✅ ✅
test:integration(事务、并发 worker、幂等、回滚、树删除) ✅ ✅
test:pg-runtime / test:mysql-runtime(HTTP + WS + 重启/断连) ✅ ✅
test:mysql-compat(30 项方言探针) — ✅
迁移幂等 / checksum 篡改拒绝 ✅ ✅

CI 已加入 mysql:8.4 服务并跑上述三道 MySQL 门禁;docker compose config 会校验 compose.yaml、compose.external-db.yaml、compose.mysql.yaml 三份文件。

本地没有 Docker,所以 compose:smoke(真实容器重启/备份恢复)和浏览器 E2E 没有在本地跑,交给本 PR 的 CI。

升级提示

  • 现有 PostgreSQL 部署不受影响:不设 MYSQL_*、URL 保持 postgres:// 即走原路径。
  • 想换 MySQL:compose.mysql.yaml 新建中枢,或把 DATABASE_URL 指向外部 mysql://;每个中枢仍需独立 database。
  • 迁移后 schema_migrations 对两种引擎各自独立维护,checksum 校验行为一致。

文档

docs/EXTERNAL_DATABASE.md(重写,双引擎)、docs/adr/0005-mysql-support.md(新增)、docs/DEPLOYMENT.md、docs/BACKUP_RESTORE.md(mysqldump 流程)、docs/ARCHITECTURE.md、README.md、官网与 CHANGELOG.md 均已同步。

用真实 MySQL 8.4 逐条验证移植依赖的 SQL 形态,结论作为后续方言层与
Store 移植的依据:

- RETURNING 不可用,需 insertId 或同事务回查
- ON DUPLICATE KEY UPDATE 支持行别名
- 生成列唯一索引可模拟部分唯一索引(墓碑并存)
- 多行 VALUES 批量写、JSON_TABLE、JSON_ARRAYAGG 均可用
- JSON_ARRAYAGG 不保序,顺序需应用层补齐
- DELETE 同表子查询被 1093/1235 拒绝,改用 DELETE ORDER BY LIMIT
- DATETIME 拒绝带 Z 的 ISO 串,参数需归一
- rank/cursor 是保留字,必须反引号引用
- prepareQuery: PostgreSQL 保留 $n 占位符并把反引号翻译成双引号;MySQL
  重排为 ? 并剥离 ::type 转换
- readDatabaseSettings: 由 DB_DIALECT 或 DATABASE_URL scheme 识别引擎,
  支持离散 MYSQL_* 变量与统一 DB_* 连接参数
- openDatabase: 同一 SqlDatabase 抽象封装 pg.Pool 与 mysql2 Pool,统一
  事务、只读快照、LISTEN 能力与会话级超时
- 迁移 runner 支持两种引擎:PostgreSQL 仍是整事务 + advisory lock,
  MySQL 改为逐文件提交 + GET_LOCK
- PostgresStore/PostgresTreeStore 重命名为 SqlStore/SqlTreeStore,接收
  SqlDatabase 抽象而不是 pg.Pool
- 事务、只读快照、LISTEN、咨询锁、保留清理按方言分支:MySQL 用会话锁、
  DELETE ORDER BY LIMIT 与进程内通知
- RETURNING 统一走 executeReturning:PostgreSQL 一语句返回,MySQL 用已知
  主键同事务回查
- jsonb 批量写改为多行 VALUES upsert,jsonb_agg 快照换成按方言的两份语句
- FILTER 聚合改写为 SUM(CASE)、ILIKE 由方言层翻译成 LIKE
- 目录读取与 bootstrap 的递归/JSON 查询按方言拆分
- PostgreSQL 迁移移入 migrations/postgres,新增 MySQL 8.4 合并基线
  0013_baseline.sql:部分唯一索引改为生成列、时间戳用 DATETIME(6)、
  jsonb 换 JSON、rank/cursor 反引号引用、子外键全部级联删除
- 迁移 runner 按引擎分支:MySQL 用 GET_LOCK 串行、逐文件提交,并按
  语句拆分脚本(连接未开多语句)
- 方言层自动引用 MySQL 保留字 rank/cursor,并翻译 ILIKE
- 运行时冒烟脚本改为双引擎 sql-runtime-smoke:MySQL 用 KILL 会话模拟
  连接中断,PostgreSQL 仍走 pg_ctl 重启
- 新增迁移矩阵一致性测试(版本对齐、表集合覆盖、保留字引用)
- 新增 compose.mysql.yaml(内置 MySQL 8.4,utf8mb4 + UTC)
- compose.external-db.yaml 改为引擎无关:DATABASE_URL 的 scheme 决定引擎
- .env.example 增加 MYSQL_* / DB_DIALECT,并注明 MySQL 的超时与 LISTEN 语义
- 重写 docs/EXTERNAL_DATABASE.md 覆盖双引擎,新增 docs/adr/0005-mysql-support.md
- DEPLOYMENT / BACKUP_RESTORE(mysqldump)/ ARCHITECTURE / README / 官网同步更新
- integration-smoke / sql-concurrency-worker 通过 openDatabase 连接,引擎由
  URL scheme 决定;空库检查按方言查询 information_schema
- 修复 MySQL 不兼容写法:同表 MAX 子查询加别名、NULLS LAST/FIRST 改为
  可移植排序键、= ANY(array) 改为 IN 列表、interval 字面量改为参数、
  保留字 CTE 改名、bootstrap 清理改用 DELETE ORDER BY LIMIT
- 方言层翻译 IS NOT DISTINCT FROM -> <=>,throwSql 识别 MySQL 约束错误码
- withIdempotency 在 MySQL 下用 owner 行锁取代 advisory lock,避免并发
  幂等 mutation 双重执行
- ci.yml / release.yml 增加 mysql:8.4 服务与 MySQL 方言、集成、运行时三道门禁;
  运行时冒烟使用独立数据库,避免复用集成冒烟的清理结果
- 增加 docker compose config 校验收紧 compose.yaml / external-db / mysql 三份文件
- 修复 perf-capacity 与 sync-bootstrap-benchmark 对 SqlDatabase 的适配
- CHANGELOG 补充 MySQL 支持与能力边界
updateSettings(按 owner 主键)、updateNote(按 task)和 deleteTimePoint
的多行 placement 墓碑都不会带 id 谓词,原来的回查键推导会抛错。改为由调用
方显式给出等值条件,并在集成冒烟里覆盖这三条路径。
@IGNGserver
IGNGserver merged commit f299cc8 into master Nov 15, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant