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>
This commit is contained in:
voidandClaude Sonnet 4.6 committed 2026-11-06 22:12:17 +08:00
commit bc4a6b504f
99 files changed
+12752

No files matched your search

@@ -0,0 +1,75 @@
## 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()` 生成指纹片段
```go
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`。