Files
archer/docs/sharding.md
T
voidandClaude Sonnet 4.6 366d61ca25 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>
2026-11-08 21:14:23 +08:00

110 lines
5.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 分片模式
| `--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` 都计入配置指纹;续跑时不一致会拒绝。