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:
1 parent
bc4a6b504f
commit
366d61ca25
49 files changed
+5099
-342
No files matched your search
@@ -0,0 +1,109 @@
|
||||
# 分片模式
|
||||
|
||||
| `--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`,即使表中只有一个日期列:
|
||||
|
||||
```bash
|
||||
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, <主键>)`
|
||||
(主键会隐式追加到索引末尾),所以当游标键恰好是主键时,`ORDER BY created_at, id` 的输出依然有序,
|
||||
分片不变量成立;若所选唯一键不是主键,日内顺序不再由索引保证,需要 filesort(结果仍正确,只是更慢)。
|
||||
但 `id` 不是显式索引列,`(created_at, id) > (?, ?)` 无法作为精确索引范围下推。
|
||||
如果仍按 chunk 反复查询,每次都得从当天起点重新扫描再过滤已读行,单日内会退化为
|
||||
O(天行数 × chunk 数)。所以改为“每天一条查询 + 长游标流式读完”:只扫一遍,
|
||||
代价是这条读查询长时间占用一条连接(同连接不能再发删除语句),删除必须换第二条连接,
|
||||
且长读快照会延长 undo 保留时间。
|
||||
|
||||
因此:**A 是推荐路径;B 是“不改表结构也能用”的兼容路径**。启动时探测索引,就是为了让
|
||||
有联合索引的用户拿到逐 chunk 短事务与精确续跑,让只有单列索引的用户不必在生产大表上
|
||||
新建索引也能完成归档;两者都没有时默认 fail-fast,而不是静默退化成全表扫描。
|
||||
|
||||
需要区分两件事:**索引决定的是执行方式,不是结果正确性**。`(created_at, id) > (?, ?)` 在没有
|
||||
联合索引时依旧按“先 `created_at`、相等再比 `id`”的字典序正确求值,只是优化器不能把它变成精确的
|
||||
索引起点;缺索引的后果是重复扫描与耗时(即路径 B 要规避的单日 O(天行数 × chunk 数) 退化),
|
||||
而不是多读、漏读或删错行。两条路径产出的行集相同,区别只在能否逐 chunk 精确 seek、
|
||||
以及读取能否短事务化。
|
||||
|
||||
`path A` 的游标比较是行构造器:
|
||||
|
||||
```sql
|
||||
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 并展示三种解释,绝不自动选择:
|
||||
|
||||
```bash
|
||||
--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` 都计入配置指纹;续跑时不一致会拒绝。
|
||||
Reference in new issue
Block a user