Files
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

51 lines
4.1 KiB
Markdown
Raw Permalink 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.
## Context
现状与动机见 `proposal.md`。与设计直接相关的约束:
- 日期扫描器(路径 A/B)按 `(分片列, 唯一键)` 排序,并把 `chunk.LastKey` 改写为 `(分片列, 键...)` 的复合游标用于续跑;`chunk.FirstKey` 仍是裸键(`internal/scan/date_a.go:72-73`、`internal/scan/date_b.go:87-92`)。
- `Purger.deleteRange` 原先直接使用 `FirstKey/LastKey`(`internal/purge/purge.go`)。放开日期模式后,单列主键会生成 `id BETWEEN <首键> AND <日期>`,复合键则因 `lo` 与 `hi` 长度不同导致参数个数不匹配。
- `DeleteChunk` 在 `--safe-auto-increment=true`(默认)且键为单列自增列时先取 `MAX(pk)`;原逻辑只要 `maxKey != nil` 就退回 IN 列表,因此默认配置下 `--bulk-delete` 实际上从不执行区间删除。
- “日期随主键递增、无回填、无 NULL/零日期”是业务承诺,运行期无法可靠验证:单个 chunk 内的键单调性检查无法发现“整块迟到数据自成一个 chunk”的情况。
## Goals / Non-Goals
**Goals:**
- 在业务承诺成立时,日期模式可以使用区间删除。
- 区间删除严格对应本次 chunk 读到的裸键范围,不因续跑游标的形状而越界。
- 保留 `--safe-auto-increment` 的语义:任何 purge 模式都不删除当前最大自增行。
- 风险以启动警告、spec 和 README 明确表达,而不是静默承担。
**Non-Goals:**
- 运行期校验全局单调不变量。
- 自动检测回填、迟到数据或 NULL/零日期。
- 改变默认删除方式(不使用 `--bulk-delete` 时仍是 IN 列表)。
## Decisions
### D1:放开校验,用启动警告承载风险
删除 `validate.go` 中“日期模式禁止 `--bulk-delete`”的分支,在 `App.execute` 中新增一条仅日期模式出现的警告。替代方案是新增一个 `--allow-unsafe-date-bulk` 之类的二次开关,但那会增加一个只为绕过自身校验而存在的参数;风险提示已经足以表达“这是显式承担前提”。
### D2:区间边界取 `chunk.Keys` 首尾
`Keys` 与扫描行一一对应且始终是裸唯一键;`FirstKey/LastKey` 中的 `LastKey` 会被日期扫描器改写成复合游标。改用 `c.Keys[0]` 与 `c.Keys[len-1]` 后,非日期模式的行为完全不变(两者本就相等),日期模式则得到正确的裸键区间。`FirstKey/LastKey` 继续只承担分片与 checkpoint 职责,不改变其语义。
### D3:区间删除中排除当前最大键,而不是退回 IN 列表
当 `--safe-auto-increment` 生效时,仍先查询 `MAX(pk)`,但区间 SQL 追加 `AND pk <> ?`,参数为当前最大键。最大键不在区间内时该条件无效果;在区间内时恰好跳过该行。这样默认配置下 `--bulk-delete` 真正生效,同时保持“不删除当前最大自增行”的契约。复合键或非自增键不会设置 `maxKey`,SQL 保持原样。
替代方案是在区间删除时把上界改成开区间 `pk < max`,但需要比较 `hi` 与 `maxKey` 的大小并处理并发删除导致的 `hi > max` 情形;`<>` 更简单且对越界情况天然安全。
### D4:测试分两层
- 单元测试:用记录型 `Execer` 直接驱动 `deleteRange`,覆盖日期式 `LastKey`、单列/复合键、以及最大键排除三种 SQL 形状。
- 集成测试:`TestIntegrationDateBulkDelete` 在 `(created_at, id)` 联合索引上分别验证 `--safe-auto-increment=false` 全删、默认开启时保留最大行;无 `ARCHER_TEST_DSN` 时自动跳过。
## Risks / Trade-offs
- **回填/迟到数据仍会误删** → 业务承诺无法运行期验证。缓解:启动警告、spec 与 README 明确前提;建议在生产使用前先用 `--dry-run` 与只导出运行核对。出现回填时应回到默认 IN 列表删除。
- **`--bulk-delete` 的并发窗口仍然存在** → 与既有取舍一致:区间内新插入且满足 `--where` 的行可能被删。日期模式下该风险进一步依赖“日期随主键递增”的假设。
- **`pk <> MAX(pk)` 在并发删除时可能多保留一行** → 只影响“少删”,方向安全;与 IN 列表模式跳过最大行的行为一致。