纯 Node.js 开发库 Schema 导出器设计

1. 架构

保留 tools/database/schema-baseline.mjs 作为治理入口，继续负责固定配置、发布版本、产物构建、历史验证、原子持久化和远程发布核对。新增 tools/database/mysql2-schema-exporter.mjs，集中负责连接、元数据读取、SHOW CREATE、依赖排序和确定性 SQL 渲染，不把一次业务流程拆成过多小文件。

development 配置
  -> schema-baseline 安全边界
  -> mysql2-schema-exporter
  -> MySQL 5.7 元数据与 SHOW CREATE
  -> 确定性 schema.sql
  -> manifest.yaml + checksum.sha256
  -> 原子版本目录

根工作区直接声明 mysql2，使治理工具拥有明确依赖。runBaselineGeneration 和 CLI 入口改为异步，外部 npm 命令保持不变。

2. format v3 与历史兼容

format v3 使用独立字段记录 Node 导出器名称、导出器版本、数据库驱动名称、驱动版本和 MySQL 服务端版本，不复用 v1/v2 的 mysql_client_version 或 mysqldump_client_version 含义。

验证器按 format_version 分支：v1/v2 保留现有字段和校验规则；v3 校验新字段。既有目录不得自动升级、格式化或重写。captured、captured_empty 和 not_applicable 状态继续保留。

3. 对象导出与顺序

导出器先从 information_schema 获取固定库的对象清单和依赖，再对每个对象执行参数受控的 SHOW CREATE：

基础表按名称排序，保留列、索引、外键、表选项和注释。
存储过程与函数按类型和名称排序。
视图依据库内依赖拓扑排序；循环或未知依赖失败。
触发器按所属表、时机、事件和执行顺序排序。
Event Scheduler 事件按名称排序。

例程、触发器和事件使用稳定 DELIMITER。标识符只能来自元数据，并统一转义反引号。导出结果删除 DEFINER、当前 AUTO_INCREMENT 值、时间、主机、用户名和客户端噪声；同一结构必须产生逐字节一致结果。

4. 完整性与安全

导出前后分别计算对象摘要，包含对象类型、名称、依赖和定义可观察版本；摘要不一致表示并发 DDL，命令失败。任何对象无法 SHOW CREATE、结果为空或类型未知时禁止跳过。

连接只允许固定 development 边界，禁用多语句，使用单连接、超时和对象数量限制。工具只查询元数据和 SHOW CREATE，不查询业务表、不锁表、不执行 DDL/DML。密码只存在于内存配置，并在所有路径通过 finally 关闭连接。

现有 SQL 安全扫描继续拒绝顶层数据操作、连接串、疑似凭据和残留 DEFINER；对象体内部合法 DML 通过分隔符解析保留。

5. 性能与异常恢复

Schema 备份不在在线请求路径。使用单连接和有限并发，目标中小型开发库 30 秒内完成；连接、查询、总时长、对象数量或响应大小超过保护值时失败。

产物先写入版本父目录中的临时目录，经过 SQL 扫描、对象计数、manifest 和 SHA-256 一致性校验后原子重命名。失败时删除临时目录，既有版本目录禁止覆盖。

6. 实施迁移

GOV-012 因缺少 v0.0.9 基线使用用户授权的一次性人工启动记录。实现通过后立即运行新导出器生成并推送 v0.0.9 基线，再重新执行自动 governance:start，证明后续开发不再依赖本机 MySQL CLI。

7. 依赖评估

选择已有技术栈中的 mysql2，避免引入不透明的第三方 dump 包。替代方案包括安装 MySQL 5.7 客户端或远程执行 mysqldump，前者在现代 macOS 上难以维护，后者增加 SSH、凭据和远程工具版本风险。退出时可替换 exporter 端口实现，但 format v3 历史基线验证必须永久保留。

3.8 KiB Raw Blame History Unescape Escape