58 lines
4.0 KiB
Markdown
58 lines
4.0 KiB
Markdown
# 纯 Node.js 开发库 Schema 导出器设计
|
||
|
||
## 1. 架构
|
||
|
||
保留 `tools/database/schema-baseline.mjs` 作为治理入口，继续负责固定配置、发布版本、产物构建、历史验证、原子持久化和远程发布核对。新增 `tools/database/mysql2-schema-exporter.mjs`，集中负责连接、元数据读取、`SHOW CREATE`、依赖排序和确定性 SQL 渲染，不把一次业务流程拆成过多小文件。
|
||
|
||
```text
|
||
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`：
|
||
|
||
1. 基础表按名称排序，保留列、索引、外键、表选项和注释。
|
||
2. 存储过程与函数按类型和名称排序。
|
||
3. 视图依据库内依赖拓扑排序；循环或未知依赖失败。
|
||
4. 触发器按所属表、时机、事件和执行顺序排序。
|
||
5. 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` 基线使用用户授权的一次性人工启动记录。实现通过后已使用 development 配置连接 MySQL 5.7.x，生成并推送 `v0.0.9` format v3 `captured_empty` 基线；随后重新执行自动 `governance:start`，证明后续开发不再依赖本机 MySQL CLI。MySQL 5.7.x 缺少 `VIEW_TABLE_USAGE` 时，导出器回退读取 `information_schema.VIEWS`，其余查询错误不降级。
|
||
|
||
## 7. 依赖评估
|
||
|
||
选择已有技术栈中的 `mysql2`，避免引入不透明的第三方 dump 包。替代方案包括安装 MySQL 5.7 客户端或远程执行 `mysqldump`，前者在现代 macOS 上难以维护，后者增加 SSH、凭据和远程工具版本风险。退出时可替换 exporter 端口实现，但 format v3 历史基线验证必须永久保留。
|