Files
voidandClaude Sonnet 4.6 bc4a6b504f Initial commit: archer, a Go-native MySQL/MariaDB table archiver
Renamed from arcdb: module path, cmd/archer, internal/archererr,
docs, build scripts and ARCHER_* environment variables.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-11-06 22:12:17 +08:00

4.0 KiB
Raw Permalink Blame History

Context

当前实现(见 proposal.md - Why):

  • cli.Config.Fingerprint()(internal/cli/hash.go:17)把 dsnFingerprint(src) 与 dsnFingerprint(dst) 的结果放进 fields map,该 map 既用于计算 config_hash,也原样写入 state.json 的 config(internal/app/app.go:492)。
  • dsnFingerprint(internal/cli/hash.go:69)手工拼接 Net|Addr|DBName|User 和 Params。
  • normalize()(internal/cli/config.go:86)统一设置 ParseTime=false,Loc 为空时置为 UTC。
  • redactDSN(internal/app/dryrun.go:155)已经采用"复制配置、清空密码、FormatDSN()"的做法。

约束:指纹必须保持可复现;密码不得落盘;旧 state.json 必须仍能读取(版本号不变)。

Goals / Non-Goals

Goals:

  • config.source / config.dest 使用可逆、可转义、生态通用的标准 DSN。
  • 指纹覆盖所有可能改变导出结果的连接参数,尤其是 charset 与 collation。

Non-Goals:

  • 不拆分"哈希输入"与"展示快照";两者继续共用同一份 fields map。
  • 不改变 state.json 的 schema 版本,不做旧指纹的兼容计算。
  • 不改变 --source / --dest 的输入语法(仍然是 MySQL DSN)。

Decisions

1. 用 FormatDSN() 生成指纹片段

func dsnFingerprint(c *mysql.Config) string {
    if c == nil {
        return ""
    }
    redacted := *c          // 值拷贝,保留未导出字段(charsets 等)
    redacted.Passwd = ""
    return redacted.FormatDSN()
}

理由:

  • charset、collation、compress、timeTruncate 是驱动的未导出字段,只有 FormatDSN 能序列化它们(dsn.go:318、322 等),手工枚举字段必然继续漏检。
  • FormatDSN 对库名做 PathEscape、对参数做 QueryEscape、对参数 key 排序(dsn.go:379-396),输出确定且无歧义。
  • 与 redactDSN 共用同一套序列化逻辑,--dry-run 与 state.json 的写法一致。

备选方案:

  • 继续竖线格式、补上 charset:仍是非标准写法,未导出字段没有稳定的读取入口。
  • 嵌套 JSON 对象:需要改 State.Config 类型与 DiffFields,收益是更精确的 diff;本次不取,记录为后续方向。

2. 用值拷贝而不是原地清空密码

mysql.Config 含未导出字段,值拷贝会一起带上,FormatDSN 因而仍能输出 charset。原地清空 Passwd 会污染调用方的配置,直接排除。

3. 保持 state.json Version = 1

指纹变化会让旧任务一次性失配。不升版本的理由:checkpoint.Load 对未知版本直接报错,会让已 complete 的目录也无法重入;而保持版本 1 时,DiffFields 会把 source 的旧竖线串与新 DSN 并列展示,用户能直观看懂差异,必要时加 --force-resume 即可。

4. 密码继续排除在指纹之外

Passwd 清空后再序列化。口令轮换不应使续跑失效,这是现有契约。

Risks / Trade-offs

  • FormatDSN 会连带覆盖 tls、timeout 等不影响产物字节的参数,这类修改也会触发续跑失配 → 方向是"宁可多报";确实需要时用 --force-resume。若未来噪声过大,再改为语义白名单。
  • 旧 state.json 需要一次性 --force-resume → 在变更说明中标注为 BREAKING,且错误信息本身会展示新旧写法。
  • Params 中若有自定义敏感参数会被写入 state.json → 与现状相同(原实现同样写入 Params),本次不扩大范围。
  • 哈希输入与展示快照仍然耦合,未来再改 state 展示格式仍会触发失配 → 接受为已知债务,不在本次处理。

Migration Plan

  1. 修改 dsnFingerprint 并补充单元测试。
  2. 验证新 state.json 中 config.source 为标准 DSN 且不含密码。
  3. 对存量任务:首轮续跑加 --force-resume;已完成任务不受影响。
  4. 回滚:还原 dsnFingerprint 即可;已写入的新格式 config 只是普通字符串,仍可读取,但指纹会再次失配,需要 --force-resume。