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,50 @@
|
||||
## 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 列表模式跳过最大行的行为一致。
|
||||
Reference in new issue
Block a user