Add archer import and allow date-mode bulk delete

archer import replays a sealed archive into an existing table: shard
selection (`--select`), SHA-256 pre-verification, idempotent modes
(`ignore`/`insert`/`replace`), and both LOAD DATA and batched-INSERT
engines. It reads manifest.jsonl strictly so corruption is reported
instead of skipped, and supports --dry-run, --allow-partial, and
per-shard workers.

--bulk-delete no longer rejects --shard-by date. Range deletion now
derives its bounds from the chunk's actual keys (date scanners rewrite
LastKey into a resumption cursor) and keeps safe-auto-increment
semantics by excluding the current max key. A startup warning documents
the monotonic-shard-column assumption.

Also splits CLI/format/sharding/progress/safety reference docs out of
the README, and adds the corresponding OpenSpec change artifacts.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
voidandClaude Sonnet 4.6 committed 2026-11-08 21:14:23 +08:00
1 parent bc4a6b504f
commit 366d61ca25
49 files changed
+5099 -342

No files matched your search

+41
View File
@@ -0,0 +1,41 @@
# 进度显示
默认 `--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。