Files
archer/README.md
T
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

15 KiB
Raw Blame History

archer

archer 是一个 Go 原生的 MySQL/MariaDB 大表归档工具。它复用了 pt-archiver 的核心语义(按唯一索引 seek 分块、file + dest + purge 三件套),并补齐了 可有序分片、可分段导入 的导出能力。

导出的分片沿扫描顺序连续、有序、无重叠:可以按主键或时间戳范围并行导入, 也可以按日期目录分批处理。

要求

  • Go 1.24+(构建)
  • MySQL 5.7+ / 8.0 或 MariaDB 10.x(运行)
  • 源表必须有主键或唯一索引;日期分片还需要分片列上的索引(见下文)

构建

go build -o archer ./cmd/archer

或使用打包脚本(Windows PowerShell / Linux shell):

./scripts/build.ps1
./scripts/build.sh

产物在 dist/ 下,版本信息通过 -ldflags -X 注入,archer --version 可查看。

最小示例

archer \
  --source 'user:pass@tcp(10.0.0.5:3306)/app' \
  --table orders \
  --where "created_at < '2025-01-01'" \
  --file ./export \
  --format dump

结果:./export/000001.<首主键>-<尾主键>.dump、manifest.jsonl、state.json。

只写目标表:

archer --source '...' --table orders --where "id < 100000" \
      --dest 'user:pass@tcp(10.0.0.9:3306)/archive' --dest-table orders

只删除(危险,需确认):

archer --source '...' --table orders --where "created_at < '2024-01-01'" --purge

先看计划,不落盘:

archer --source '...' --table orders --where "1=1" --file /tmp/out --dry-run

分片模式

--shard-by 行为 文件
none(默认) 单文件 <seq>.<lo>-<hi>.<format>
count 每 --shard-rows 行封片,流式滚动 同上,序号递增
date 每个日期一个目录;同一天内可再按 --shard-rows 切分 date=YYYY-MM-DD/<seq>.<lo>-<hi>.<format>

三种模式都保证:

  • 分片按扫描顺序编号;
  • 相邻分片的主键范围连续、不重叠;
  • 分片合并等于本次扫描读取到的全部行;
  • 文件名中的 lo/hi 是该分片实际首尾键;
  • 同一时刻只有一个活跃分片文件(因此没有 fd 上限问题)。

--chunk-size(每次 SELECT 的行数、事务大小、checkpoint 粒度)与 --shard-rows 相互独立,一个 chunk 可以跨多个分片。

分片先写 <seq>.partial,flush + fsync 后原子重命名为最终文件名。

日期分片

必须显式指定 --shard-column,即使表中只有一个日期列:

archer --source '...' --table orders --where "1=1" \
      --file ./export --shard-by date --shard-column created_at

启动时探测索引并选择路径:

索引 路径 读事务 / 删除
(created_at, id) 联合索引 A:(created_at, id) keyset 分块 每 chunk 一个短查询;dest 写入与 purge 可放同一事务
只有 created_at 单列索引 B:逐日枚举 + 长游标流式读取 读取是一个长查询、占用独立连接;写入/删除仍按 chunk 提交,purge 使用第二条连接
都没有 报错退出;--allow-full-scan 可覆盖 —

为什么分两条路径

分界不是实现偏好,而是索引能力决定了两件事:能否精确 seek,以及读取能否短事务化。

  • 路径 A:联合索引 (created_at, id) 让 (created_at, id) > (?, ?) 成为一次精确的索引范围定位。 每个 chunk 都是 O(chunk) 的短查询,游标就是一个元组,天然可以按 chunk 续跑; dest 写入和 purge 删除还能放进同一个事务,跨 chunk 之间不持有任何长事务。
  • 路径 B:只有 created_at 单列索引。InnoDB 二级索引的物理顺序仍然是 (created_at, id) (主键会隐式追加到索引末尾),所以 ORDER BY created_at, id 的输出依然有序,分片不变量成立。 但 id 不是显式索引列,(created_at, id) > (?, ?) 无法作为精确索引范围下推。 如果仍按 chunk 反复查询,每次都得从当天起点重新扫描再过滤已读行,单日内会退化为 O(天行数 × chunk 数)。所以改为“每天一条查询 + 长游标流式读完”:只扫一遍, 代价是这条读查询长时间占用一条连接(同连接不能再发删除语句),删除必须换第二条连接, 且长读快照会延长 undo 保留时间。

因此:A 是推荐路径;B 是“不改表结构也能用”的兼容路径。启动时探测索引,就是为了让 有联合索引的用户拿到逐 chunk 短事务与精确续跑,让只有单列索引的用户不必在生产大表上 新建索引也能完成归档;两者都没有时默认 fail-fast,而不是静默退化成全表扫描。

path A 的游标比较是行构造器:

WHERE (<where>)
  AND (created_at, id) > (?, ?)
ORDER BY created_at, id
LIMIT ?

这里的 id 不是特指名为 id 的列,而是所选唯一键(优先主键,没有主键时用第一个唯一索引)。 日期分片本身只要求“同一天的行落在同一个文件”,并不要求按主键排序,但游标仍然需要这个唯一键:

  1. created_at 不唯一:同一秒可能有大量行。只比较 created_at 时,> 会跳过同秒的其余行, >= 会反复重读同一批行(只能靠 OFFSET 跳过,深分页会退化)。加上唯一键构成全序, 游标 (created_at, id) > (?, ?) 才能既不重不漏地向前推进。
  2. 断点续跑必须能唯一定位一行:state.json 里的游标就是这个元组;只有时间戳无法区分 同秒的行,重启后会重复或跳过。
  3. 归档语义本身也需要主键:文件名里的 pk_lo/pk_hi、IN 列表删除、 --safe-auto-increment 保护最大自增行,都按唯一键工作。

所以准确说法是:日期决定文件归属,唯一键只在日期内部提供全序和可恢复的游标。 如果业务上日期列本身唯一(一行一个时间点),理论上不需要 tie-breaker,但本工具仍要求 表有唯一键,因为删除和清单语义都依赖它。

NULL 日期行先单独扫描(created_at IS NULL),再扫描非 NULL 行,保持有序。

零日期:默认报错并输出行主键;--zero-date bucket 将其放入 date=0000-00-00 分片。

整数 epoch 列:必须声明单位,否则会采样 min/max 并展示三种解释,绝不自动选择:

--shard-column ts --shard-column-type epoch-seconds
# 可选:epoch-seconds / epoch-milliseconds / epoch-microseconds

时区:

列类型 日期归属
DATE / DATETIME 原值,不做换算
TIMESTAMP 连接会话 time_zone
epoch 整数 --shard-time-zone(默认 UTC)

--shard-time-zone 与 DSN 中的 time_zone 都计入配置指纹;续跑时不一致会拒绝。

输出格式

--format 说明
dump(默认) MySQL LOAD DATA 兼容的 TSV:TAB 分隔、\N 表示 NULL、MySQL 转义表、无表头
csv RFC4180:逗号分隔、表头、双引号转义、CRLF;--csv-null 覆盖 NULL 标记
jsonl 每行一个 JSON 对象;DECIMAL 为字符串、BLOB 为 base64、时间列为 RFC3339、NULL 为 null

--compress none|gzip|zstd|xz,默认 none。每个分片独立压缩,扩展名分别为 .gz / .zst / .xz。压缩文件可单独解压后导入。

--compress-level 1..9,默认 3。1–9 是跨压缩器的统一档位:数值越大压缩率越高、吞吐越低,9 表示该压缩器的最强档位。各格式的映射:

档位 gzip zstd xz 字典
1 1 fastest 1 MiB
2 2 fastest 2 MiB
3(默认) 3 default 4 MiB
4 4 default 4 MiB
5 5 default 8 MiB
6 6 better 8 MiB
7 7 better 16 MiB
8 8 better 32 MiB
9 9 best 64 MiB

默认档位与引入该参数前的版本保持一致,存量任务可直接续跑;非默认档位会计入配置指纹,续跑时不一致会被拒绝。--compress none 不能搭配非默认档位。

xz 由纯 Go 库实现,产物是标准 xz 流,xz -dc 可直接解码。其压缩吞吐明显低于 gzip/zstd,适合长期归档、写入速度不敏感的场景;zstd 则在吞吐与压缩率之间更均衡。

导入

# dump -> MySQL(列顺序一致时)
zcat 000001.1-1000000.dump.gz | mysql -e "LOAD DATA LOCAL INFILE '/dev/stdin' INTO TABLE orders"

# xz -> MySQL
xz -dc 000001.1-1000000.dump.xz | mysql -e "LOAD DATA LOCAL INFILE '/dev/stdin' INTO TABLE orders"

# csv -> PostgreSQL
gunzip -c 000001.1-1000.csv.gz | psql -c "\copy orders FROM STDIN WITH (FORMAT csv, HEADER true)"

# csv -> ClickHouse
clickhouse-client --query "INSERT INTO orders FORMAT CSVWithNames" < 000001.csv

# jsonl -> ClickHouse
clickhouse-client --query "INSERT INTO orders FORMAT JSONEachRow" < 000001.jsonl

进度显示

默认 --progress auto:stderr 是终端时在最后一行原地刷新,重定向到文件或管道时不输出进度。 进度与警告统一写 stderr;--dry-run 与 --statistics 仍写 stdout,因此 archer ... > result.txt 不会把进度混进结果。

取值 行为
auto(默认) stderr 是终端时显示实时进度,否则静默
on 始终显示;非终端时每个间隔输出一行完整 key=value
off / 0 关闭
N>0 开启,并在每处理 N 行时额外输出一行

--progress-interval(默认 1s)是最小刷新间隔。终端模式用 \r 覆盖同一行并以空格补齐, 不使用 ANSI 清行或颜色,兼容 Windows conhost;行宽超过 100 字符时按优先级裁掉字节数、 分片序号,再缩短进度条,不换行。

进度包含:已处理行数、约 5 秒窗口速率、当前阶段与阶段耗时、本次运行 elapsed, 存在分片时包含分片序号,写文件时包含已写字节。阶段依次为 probe → resume → estimate → scan → file → db → checkpoint → finalize; 等待副本延迟时显示 lag-wait 与等待原因,而不是一条孤立的 waiting: 消息。 单日长查询、fsync 与 lag 等待期间进度仍按间隔刷新。

总量估算只使用有界 MIN/MAX 查询(独立连接 + 2 秒超时,绝不 COUNT(*)):

场景 口径 显示
--shard-by date 分片列的 MIN/MAX 天范围 estimate=day、day 37/120、~58%、eta ~1m36s
非日期、单列整数唯一键 键的 MIN/MAX estimate=key、~58%、eta ~1m36s
复合键、字符串/二进制键 不适用 estimate=none,只显示行数与速率

百分比与 ETA 都带 ~;ETA 按本次运行的推进速率与剩余量计算,不使用"已用时间 ÷ 百分比"。 日期模式按天跳变、键模式在键有空洞或分布不均时偏差较大,这些值都是估算而非精确进度, 不影响归档逻辑。

续跑后进度从 state.json 的累计 rows_done 起算,不会从零重来;本次运行写回的 rows_done 同样是累计值(续跑前已提交 + 本次提交)。旧版本写入的 checkpoint 只记录 上次运行的行数,升级后首次续跑可能偏低,完成后即恢复累计语义。

按 Ctrl+C 时先停止刷新、清除实时行并输出最终快照,然后封存当前分片并写 checkpoint, 退出码保持 130。

清单与断点

每个分片关闭后向 manifest.jsonl 追加一行并 fsync:

{"seq":1,"path":"000001.1-1000000.dump","pk_lo":"1","pk_hi":"1000000","rows":1000000,"bytes":12345678,"sha256":"...","closed_at":"2026-11-06T12:00:00Z"}

state.json 在每个 chunk 提交后原子更新(tmp + fsync + rename),记录:

  • config_hash 与完整的配置指纹;
  • 扫描游标(主键、日期键或当前日期);
  • 当前日期桶与分片序号;
  • 已处理行数。

续跑时使用相同输出目录与配置即可。指纹不一致会拒绝,除非显式 --force-resume;不一致的字段会列在错误信息里。密码不参与指纹,允许凭据轮换。

已封分片的文件如果缺少 manifest 记录(例如在 rename 与 manifest 追加之间崩溃), 续跑会自动识别并补录,不会被覆盖。带 --purge 时还会保留活动分片的 .partial 与 sidecar 元数据,续跑时截断到一致偏移并追加,避免已删除数据丢失。

一致性

at-least-once。文件写入与数据库提交不在同一个原子域内,崩溃后重跑可能重复写入 已处理的行,但不会丢失已提交的数据。导入端可用 INSERT IGNORE / 去重逻辑处理。

扫描期间不提供快照一致性:只保证读取到的行,并发写入可能改变行集合。

安全说明

  • --purge 会删除源表数据。先用 --dry-run,再只导出核对,最后才启用。
  • --bulk-delete 改为按主键区间删除,可能删除扫描期间新插入且满足 --where 的行; 默认关闭,日期分片模式禁止使用。
  • --safe-auto-increment 默认开启,purge 时不会删除当前最大自增主键行。
  • 日期路径 B 会长时间持有一个只读查询与连接,可能推迟 undo 清理;用 --max-lag 限制主从延迟,优先为分片列建立 (shard_column, pk) 联合索引走路径 A。
  • --where 原样拼入 SQL,等同于 pt-archiver 的信任模型;不要让不可信输入进入该参数。
  • 配置指纹包含 DSN 中的 time_zone;时区漂移会导致同一行落到相邻日期,续跑会被拒绝。

退出码

码 含义
0 成功
2 配置错误
3 连接错误
4 写入/文件错误
5 校验失败(索引、指纹、分片列等)
130 被 SIGINT/SIGTERM 中断(已 flush 当前分片并写 checkpoint)
1 其他

参数对照:pt-archiver

pt-archiver archer 说明
--source --source MySQL DSN
--dest --dest MySQL DSN
--file --file archer 中为输出目录
--limit --limit / --chunk-size --limit 为隐藏别名;语义是每次 SELECT 行数
--txn-size — chunk 即事务,不提供独立事务粒度
--where --where 必填
--columns --columns 逗号分隔
--purge --purge 默认不删除
--bulk-delete --bulk-delete 依赖 --purge
--replace --replace
--ignore --insert-ignore
--safe-auto-increment --safe-auto-increment 默认开启
--max-lag --max-lag
--check-slave-lag --check-replica-lag 传副本 DSN
--check-interval --check-interval
--retries --retries
--dry-run --dry-run archer 输出解析后配置、索引探测与 SQL
— --shard-by / --shard-rows / --shard-column archer 扩展
— --format / --compress / --compress-level archer 扩展
— --progress / --progress-interval archer 扩展;默认 auto,写 stderr
— --allow-full-scan / --force-resume archer 扩展

非目标(v1)

  • 非 MySQL 数据源
  • Parquet / Arrow 输出
  • 字符串日期列分片
  • 预计算边界并行导出
  • 文件侧 exactly-once
  • PXC Flow Control 适配

开发

go test ./...
# 集成测试(需要 MySQL):
ARCHER_TEST_DSN='root@tcp(127.0.0.1:3306)/archer_test' go test ./internal/app -run TestIntegration -v

集成测试会创建并删除 it_* 表;LOAD DATA LOCAL INFILE 相关用例需要服务器开启 local_infile。