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:
commit
bc4a6b504f
99 files changed
+12752
No files matched your search
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-11-06
|
||||
@@ -0,0 +1,3 @@
|
||||
# normalize-state-config
|
||||
|
||||
state.json 的 config.source/dest 改用标准 MySQL DSN(去密码),并修复 charset 等参数未纳入指纹的问题
|
||||
@@ -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`。
|
||||
@@ -0,0 +1,27 @@
|
||||
## Why
|
||||
|
||||
`state.json` 的 `config.source` / `config.dest` 目前由 `dsnFingerprint`(internal/cli/hash.go)用竖线拼成 `tcp|host:3306|db|user`。这既不是 MySQL 生态的标准写法,也无法转义;更严重的是它只读取 `Net/Addr/DBName/User/Params`,导致 `charset`、`collation` 等被驱动收进结构体字段的参数**完全不参与指纹校验**——续跑时把 `charset=utf8mb4` 改成其他编码不会被发现,同一份导出会出现混合编码的分片。
|
||||
|
||||
## What Changes
|
||||
|
||||
- `state.json` 中的 `config.source` / `config.dest` 改为标准 MySQL DSN(去掉密码),例如 `root@tcp(s1.void01.com:3306)/lexis?charset=utf8mb4`。
|
||||
- 配置指纹改用同一份规范化 DSN 计算,覆盖驱动解析出的全部连接参数(密码除外),从而把 `charset`、`collation`、`loc` 等纳入续跑校验。
|
||||
- 与 `--dry-run` 的展示格式(`redactDSN`,internal/app/dryrun.go)保持一致,工具的"用户可见连接串"只有一种写法。
|
||||
- **BREAKING**:指纹取值变化,旧版本写入的 `state.json` 会被判定为配置不同。续跑旧任务需要一次性传入 `--force-resume`;`state.json` 版本号不变(仍为 1),旧文件仍可读取并展示差异。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
(无)
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `archive-core`: 断点续跑要求中,明确配置指纹必须覆盖源/目标连接的规范化参数(含字符集与排序规则),并规定 `state.json` 中连接信息的存储形态为标准 DSN。
|
||||
|
||||
## Impact
|
||||
|
||||
- 代码:`internal/cli/hash.go`(`dsnFingerprint` 改为复制配置、清空 `Passwd`、调用 `FormatDSN`)。
|
||||
- 测试:`internal/cli/cli_test.go` 增加 charset/参数变化的指纹断言与 `state.json` 快照断言。
|
||||
- 数据:`state.json` 的 `config` 内容形态变化,触发一次性续跑校验失败。
|
||||
- 文档:README 中关于 `state.json` 记录的描述无需改动;`--dry-run` 输出不变。
|
||||
@@ -0,0 +1,40 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 断点续跑
|
||||
|
||||
系统 SHALL 在每个 chunk 提交后原子更新 `state.json`,记录配置指纹与游标位置。`state.json` 中记录的源连接与目标连接 MUST 采用标准 MySQL DSN 形式(去除密码),例如 `user@tcp(host:3306)/db?charset=utf8mb4`。续跑时 MUST 校验源、表、过滤条件、列、分片参数、时区、输出格式、压缩设置,以及源/目标连接的全部规范化参数(含字符集与排序规则)的指纹;不一致时 MUST 拒绝续跑,除非显式传入 `--force-resume`。密码 MUST NOT 计入指纹,也 MUST NOT 写入 `state.json`。压缩档位仅在启用压缩且档位不是默认值 3 时纳入指纹,以保证默认配置的存量任务可以无缝续跑。
|
||||
|
||||
#### Scenario: 配置一致时续跑
|
||||
|
||||
- **WHEN** 上次运行在 chunk 中途退出,且本次配置指纹一致
|
||||
- **THEN** 系统从 `state.json` 记录的游标位置继续,不重复处理已提交的 chunk
|
||||
|
||||
#### Scenario: 配置被修改
|
||||
|
||||
- **WHEN** 续跑时 `--shard-time-zone` 与 `state.json` 记录不一致,且未传 `--force-resume`
|
||||
- **THEN** 系统报错并列出不一致的字段,拒绝开始扫描
|
||||
|
||||
#### Scenario: 压缩档位被修改
|
||||
|
||||
- **WHEN** 续跑时 `--compress-level` 与 `state.json` 记录不一致,且未传 `--force-resume`
|
||||
- **THEN** 系统报错并列出 `compress_level` 字段的变化,拒绝开始扫描
|
||||
|
||||
#### Scenario: 默认档位兼容存量任务
|
||||
|
||||
- **WHEN** `state.json` 由引入压缩档位之前的版本写入,且本次使用默认档位 3
|
||||
- **THEN** 指纹一致,系统正常续跑
|
||||
|
||||
#### Scenario: 连接字符集被修改
|
||||
|
||||
- **WHEN** 续跑时 `--source` 的 `charset` 或 `collation` 与 `state.json` 记录不一致,且未传 `--force-resume`
|
||||
- **THEN** 系统报错并列出 `source` 字段的变化,拒绝开始扫描
|
||||
|
||||
#### Scenario: 密码轮换
|
||||
|
||||
- **WHEN** 续跑时仅 `--source` 或 `--dest` 的密码与上次运行不同
|
||||
- **THEN** 指纹一致,系统正常续跑
|
||||
|
||||
#### Scenario: 连接信息的存储形态
|
||||
|
||||
- **WHEN** 查看任意一次运行生成的 `state.json`
|
||||
- **THEN** `config.source` 与 `config.dest` 为标准 MySQL DSN,且不包含密码明文
|
||||
@@ -0,0 +1,17 @@
|
||||
## 1. 指纹生成
|
||||
|
||||
- [x] 1.1 将 `internal/cli/hash.go` 的 `dsnFingerprint` 改为:`nil` 返回空串;否则值拷贝 `mysql.Config`、清空 `Passwd`、返回 `FormatDSN()`
|
||||
- [x] 1.2 更新 `Fingerprint` 与 `dsnFingerprint` 的注释,说明输出为标准 DSN、覆盖驱动全部已解析参数、密码除外
|
||||
|
||||
## 2. 测试
|
||||
|
||||
- [x] 2.1 新增单元测试:`charset` 或 `collation` 不同时指纹不同
|
||||
- [x] 2.2 新增单元测试:仅密码不同时指纹相同
|
||||
- [x] 2.3 新增单元测试:指纹中不含密码明文,`dest` 为空时片段为空串
|
||||
- [x] 2.4 新增断言:`state.json` 的 `config.source` 等于 `redactDSN` 输出的标准 DSN(可复用现有 app 测试夹具)
|
||||
|
||||
## 3. 验证
|
||||
|
||||
- [x] 3.1 运行 `go test ./...`(无数据库环境下跳过集成测试)
|
||||
- [ ] 3.2 用同一 `--source` 分别以不同密码、不同 `charset` 运行 `--dry-run` 与续跑,确认前者指纹一致、后者报错并展示 `source` 差异
|
||||
- [ ] 3.3 用旧版 `state.json` 续跑一次,确认报错信息可读,且 `--force-resume` 后正常继续并改写为新格式
|
||||
Reference in new issue
Block a user