Files
ssw-ontology/docs/BACKUP.md
T
admin e7b39805fb feat(backup): 按 schema 镜像 + 请求级 search_path 切库 (issue #4 #5 后续)
「让客户端敢操作」的关键能力:写前/写后打一份快照 → 任意 GET 带 X-Snapshot-Id
 头即可命中 backups_<id> schema 的同名表(业务 SQL 不带 schema 前缀照样切)。

 设计要点:
   - 备份 = 独立 schema backups_<id>(真表,不是单存 JSONB)—— 查询性能与活库一致
   - snapshotRouter 中间件:BeginTx + SET LOCAL search_path → 把 a.pool 临时换
     为事务视图 txPool → handler 结束 commit + 还原 a.pool。业务代码一行不改。
   - a.pool 字段类型从 *pgxpool.Pool 升级为 dbRunner interface(中间件可换 txPool)。
   - 11 个 helper 函数签名同步改为 dbExec(与现有 dbExec 共存,无破坏性)。
   - 写方法(POST/PUT/PATCH/DELETE)带快照头 → 403 拒绝(mistake-safety)。

 接口:
   - POST /api/v1/backups 创建
   - GET /api/v1/backups 列表
   - GET /api/v1/backups/:id 元信息(含 schema_name)
   - GET /api/v1/backups/:id/switch 切库提示
   - DELETE /api/v1/backups/:id 级联删 schema
   - 支持 X-Snapshot-Id (直接 run id) + X-Snapshot-Ts (秒级时间戳) 两种切换入口

 MCP 工具 (5 个):backup_create / backup_list / backup_inspect / backup_switch / backup_delete

 测试 (22 个全绿,~5.5s 集成):
   - SnapshotRouter:改前建快照 → 改后读快照只见改前
   - SnapshotSearchPathPersist:不污染下一个请求
   - SnapshotByTimestamp:ts 头也能切库
   - SnapshotDeleteCleansSchema:delete 真 DROP schema
   - BackupLifecycle / BackupDiffAfterMutation:完整 create→list→inspect→switch→delete

 文档:docs/BACKUP.md 写清用法、机制、客户端工作流;CHANGELOG.md [1.3.0]。
2026-09-07 11:35:47 +08:00

3.5 KiB
Raw Blame History

数据备份(v1.3.0,按 schema 镜像 + 请求级切库)

让 AI 客户端敢操作的关键能力:写前打个保险 → 改坏了能从快照读原样。

一句话工作流

  1. 改前:POST /api/v1/backups 打一份快照 → 拿到 id=42
  2. 改活库:POST /api/v1/objects {pk: ...} 写入
  3. 改后想确认范围:再读 GET /api/v1/backups / GET /api/v1/backups/42 看元信息
  4. 想看「改前长什么样」?带 X-Snapshot-Id: 42 头查同一接口 → 命中快照库(不是活库)

核心机制

每个备份 = 一个独立 schema backups_<id>,包含 23张业务表的同结构副本 + 一致的 INSERT...SELECT 数据。

读请求带 X-Snapshot-Id 时:

  • snapshotRouter 中间件 BeginTx + SET LOCAL search_path TO backups_42, public
  • 把 a.pool 字段临时换为 *txPool(事务视图)
  • 业务代码 a.pool.Query / .QueryRow / .Exec 一行不改,自动走事务视图
  • handler 结束 → commit + 还原 a.pool

写方法(POST/PUT/PATCH/DELETE)带快照头 → 403 拒绝(mistake-safety)。

接口清单

接口 方法 用途
POST /api/v1/backups 创建快照 body {name?, notes?}
GET /api/v1/backups 列表 ?limit=50&offset=0
GET /api/v1/backups/:id 元信息 含 schema_name=backups_<id>
GET /api/v1/backups/:id/switch 切库提示 返回「下次请求带什么头」
DELETE /api/v1/backups/:id 级联删 schema 清理用

全部需要 manager 主体(X-Principal: manager 或登录 session)。

切库方法(任意 HTTP 请求通用)

X-Snapshot-Id: 42              # 直接 run id
X-Snapshot-Ts: 1700000000      # 秒级时间戳 → EXTRACT(EPOCH FROM created_at) <= ts 的最近 run

任一即可(同时带时以 ID 优先)。响应头会回 X-Snapshot-Active: backups_42 确认当前生效的 schema。

GET / HEAD / OPTIONS 才能切,写方法带快照头直接 403。

MCP 工具

工具集(5 个):

backup_create({name?, notes?})           # 创建快照
backup_list({limit?, offset?})           # 列出快照
backup_inspect({id)                      # 元信息 + schema_name
backup_switch({id)                       # 切库提示(让 MCP 客户端知道下次该带什么头)
backup_delete({id)                       # 级联删

客户端典型用法

// 1. 备份
const backup = await mcp.call("backup_create", { name: "before-batch-import" });
const snapId = backup.id;

// 3. 导入一批数据(万一出问题可以快速看原样)
await mcp.call("batch_create_objects", { items: [...] });

// 4. 检查导入是否有问题 — 用快照头对比
const oldView = await mcp.call("query_related", {
  type: "Device",
  filters: { ... },
  /* MCP 客户端 SDK 不直接支持加 HTTP 头,
     让 WorkBuddy 把 X-Snapshot-Id 注入下一批只读调用即可 */
});

不做什么

  • 不提供 restore 到线上:写入回滚极易连锁错位,让客户拿到 dump 自行恢复是更稳的路径。
  • 不自动备份:每次 create/update/delete 不自动触发,让客户端掌握节奏,避免 object_changes 表爆炸。
  • 不限制快照数量:当前默认永久保留,由 DELETE /backups/:id 主动清理。

测试覆盖

  • go test -short 跑 11 个纯函数单测
  • go test -tags=integration 跑 11 个集成测试(含快照路由 4 个 + 备份生命周期 2 个 + 之前治理 5 个)

完整 runbook 见 docs/TESTING.md。