Renamed from arcdb: module path, cmd/archer, internal/archererr, docs, build scripts and ARCHER_* environment variables. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
178 lines
8.5 KiB
Markdown
178 lines
8.5 KiB
Markdown
# archive-core Specification
|
||
|
||
## Purpose
|
||
|
||
定义 archer 如何按唯一索引分块读取源表,并以固定顺序完成文件写入、目标表写入与源行删除,同时提供复制延迟保护、安全护栏和可中断续跑能力。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 唯一索引 seek 分块扫描
|
||
|
||
系统 SHALL 以源表的一个唯一索引(优先主键)作为扫描游标。每个 chunk 的查询 MUST 使用“索引键大于上一次尾值”的条件、按索引列 `ORDER BY`、并带 `LIMIT chunk-size`;系统 MUST NOT 使用 `OFFSET` 翻页。返回行数小于 `chunk-size` 时,系统 SHALL 结束扫描。
|
||
|
||
#### Scenario: 主键连续
|
||
|
||
- **WHEN** 源表主键为连续的 1..N,且 `--chunk-size 2000`
|
||
- **THEN** 系统按 2000 行一个 chunk 依次读取,直到最后一个不足 2000 行的 chunk
|
||
|
||
#### Scenario: 主键存在空洞
|
||
|
||
- **WHEN** 主键序列为 1,2,100,101,且 `--chunk-size 2`
|
||
- **THEN** 第一个 chunk 返回 1,2,第二个 chunk 从 `id > 2` 继续并返回 100,101,不会跳过或重复
|
||
|
||
#### Scenario: 无可用唯一索引
|
||
|
||
- **WHEN** 源表既没有主键也没有唯一索引,且用户未指定索引
|
||
- **THEN** 系统在开始扫描前报错退出,并提示需要唯一索引
|
||
|
||
### Requirement: chunk 即事务
|
||
|
||
每个 chunk SHALL 构成唯一的事务边界,`--chunk-size` 同时决定 SELECT 批量、事务大小和 checkpoint 粒度。系统 SHALL NOT 提供跨 chunk 的事务,也 SHALL NOT 提供独立的 `--txn-size` 参数。
|
||
|
||
#### Scenario: 源表与目标表在同一实例
|
||
|
||
- **WHEN** `--source` 与 `--dest` 指向同一 MySQL 实例,且同时启用 dest 与 purge
|
||
- **THEN** 目标表写入与源行删除在同一个事务中提交,二者要么同时生效要么同时回滚
|
||
|
||
#### Scenario: 源表与目标表在不同实例
|
||
|
||
- **WHEN** `--source` 与 `--dest` 指向不同实例
|
||
- **THEN** 系统使用两个连接分别提交,并在任一步失败时按 `--retries` 重试;已提交的目标表写入可能在重跑时重复,行为为 at-least-once
|
||
|
||
### Requirement: 三件套提交顺序
|
||
|
||
当 file、dest、purge 中任意多项同时启用时,系统 MUST 对每个 chunk 按固定顺序执行:写文件、写目标表、删除源行、提交事务并更新 checkpoint。任何前置步骤失败时,系统 MUST NOT 执行后续步骤,也 MUST NOT 推进 checkpoint。
|
||
|
||
#### Scenario: 文件写入失败
|
||
|
||
- **WHEN** 写文件返回错误
|
||
- **THEN** 系统不写目标表、不删除源行、不推进 checkpoint,并以非零码退出
|
||
|
||
#### Scenario: 目标表写入失败
|
||
|
||
- **WHEN** 文件写入成功但目标表插入失败
|
||
- **THEN** 系统删除源行,回滚本次事务,不推进 checkpoint,并以非零码退出
|
||
|
||
### Requirement: 输出目标约束
|
||
|
||
系统 SHALL 要求 `--file`、`--dest`、`--purge` 至少启用一个,并且 `--where` 必填。三者可以任意组合,包括只导出文件、只删除、或文件与目标表同时输出。
|
||
|
||
#### Scenario: 只删不写
|
||
|
||
- **WHEN** 用户只指定 `--purge` 和 `--where`
|
||
- **THEN** 系统仅按 chunk 删除匹配行,不生成任何文件
|
||
|
||
#### Scenario: 文件与目标表同时输出
|
||
|
||
- **WHEN** 用户同时指定 `--file` 与 `--dest`
|
||
- **THEN** 同一批行既写入分片文件,也写入目标表
|
||
|
||
### Requirement: 目标表写入模式
|
||
|
||
目标表写入 SHALL 支持普通插入、`INSERT IGNORE` 与 `REPLACE` 三种模式,三者互斥。系统 MUST 使用多行批量插入,并在单条语句可能超过 `max_allowed_packet` 时自动拆分为多条语句。
|
||
|
||
#### Scenario: 默认插入遇到重复主键
|
||
|
||
- **WHEN** 使用默认插入模式,且目标表已存在相同主键
|
||
- **THEN** 该 chunk 失败并回滚,系统报告重复键错误
|
||
|
||
#### Scenario: ignore 模式遇到重复主键
|
||
|
||
- **WHEN** 使用 `--insert-ignore`
|
||
- **THEN** 重复行被跳过,其余行写入成功,chunk 正常提交
|
||
|
||
### Requirement: 删除语义
|
||
|
||
默认情况下,系统 MUST 以主键 IN 列表删除当前 chunk 实际读取到的行,并将过长的列表分批。启用 `--bulk-delete` 时,系统 SHALL 改为按首尾主键区间删除,并 MUST 在语句中附带原始 `--where` 条件。`--bulk-delete` 依赖 `--purge`,且在日期分片模式下 MUST 被拒绝。
|
||
|
||
#### Scenario: 默认 IN 列表删除
|
||
|
||
- **WHEN** 一个 chunk 读取到主键 1001..3000,且 `--where "created_at < '2026-01-01'"`
|
||
- **THEN** 系统生成 `DELETE ... WHERE id IN (1001,...,3000)`,不删除未被读取的行
|
||
|
||
#### Scenario: 区间删除附带回填条件
|
||
|
||
- **WHEN** 启用 `--bulk-delete`,chunk 首尾主键为 1001 与 3000
|
||
- **THEN** 系统生成 `DELETE ... WHERE id BETWEEN 1001 AND 3000 AND (<where>)`
|
||
|
||
#### Scenario: 日期模式启用区间删除
|
||
|
||
- **WHEN** `--shard-by date` 与 `--bulk-delete` 同时出现
|
||
- **THEN** 系统在启动校验阶段报错退出,不执行任何查询
|
||
|
||
### Requirement: 复制延迟保护
|
||
|
||
当指定 `--check-replica-lag` 时,系统 SHALL 在每次拉取前检查该副本的延迟;延迟超过 `--max-lag` 或复制未运行时,系统 MUST 暂停并在 `--check-interval` 后重试。
|
||
|
||
#### Scenario: 延迟超限
|
||
|
||
- **WHEN** `--max-lag 1s`,副本延迟为 5s
|
||
- **THEN** 系统暂停拉取,直到延迟降到 1s 以下
|
||
|
||
#### Scenario: 副本复制中断
|
||
|
||
- **WHEN** 被检查的副本复制线程未运行
|
||
- **THEN** 系统持续等待并周期性重试,不继续归档
|
||
|
||
### Requirement: 安全护栏
|
||
|
||
系统 SHALL 默认启用 `--safe-auto-increment`,禁止通过 purge 删除当前最大自增主键行。`--dry-run` 时系统 MUST 只打印将要执行的 SQL 与实际生效配置,不连接写入、不创建或修改任何文件。
|
||
|
||
#### Scenario: 保护最大自增行
|
||
|
||
- **WHEN** purge 范围包含源表当前 `MAX(pk)`,且 `--safe-auto-increment` 为默认值
|
||
- **THEN** 该行不被删除,系统记录一条警告
|
||
|
||
#### Scenario: dry-run 无副作用
|
||
|
||
- **WHEN** 用户指定 `--dry-run`
|
||
- **THEN** 系统打印每条 SQL 与解析后的配置后退出,输出目录不产生任何文件
|
||
|
||
### Requirement: 断点续跑
|
||
|
||
系统 SHALL 在每个 chunk 提交后原子更新 `state.json`,记录配置指纹与游标位置。`state.json` 中记录的源连接与目标连接 MUST 采用标准 MySQL DSN 形式(去除密码),例如 `user@tcp(host:3306)/db?charset=utf8mb4`。续跑时 MUST 校验源、表、过滤条件、列、分片参数、时区、输出格式、压缩设置,以及源/目标连接的全部规范化参数(含字符集与排序规则)的指纹;不一致时 MUST 拒绝续跑,除非显式传入 `--force-resume`。密码 MUST NOT 计入指纹,也 MUST NOT 写入 `state.json`。压缩档位仅在启用压缩且档位不是默认值 3 时纳入指纹,以保证默认配置的存量任务可以无缝续跑。
|
||
|
||
#### Scenario: 配置一致时续跑
|
||
|
||
- **WHEN** 上次运行在 chunk 中途退出,且本次配置指纹一致
|
||
- **THEN** 系统从 `state.json` 记录的游标位置继续,不重复处理已提交的 chunk
|
||
|
||
#### Scenario: 配置被修改
|
||
|
||
- **WHEN** 续跑时 `--shard-time-zone` 与 `state.json` 记录不一致,且未传 `--force-resume`
|
||
- **THEN** 系统报错并列出不一致的字段,拒绝开始扫描
|
||
|
||
#### Scenario: 压缩档位被修改
|
||
|
||
- **WHEN** 续跑时 `--compress-level` 与 `state.json` 记录不一致,且未传 `--force-resume`
|
||
- **THEN** 系统报错并列出 `compress_level` 字段的变化,拒绝开始扫描
|
||
|
||
#### Scenario: 默认档位兼容存量任务
|
||
|
||
- **WHEN** `state.json` 由引入压缩档位之前的版本写入,且本次使用默认档位 3
|
||
- **THEN** 指纹一致,系统正常续跑
|
||
|
||
#### Scenario: 连接字符集被修改
|
||
|
||
- **WHEN** 续跑时 `--source` 的 `charset` 或 `collation` 与 `state.json` 记录不一致,且未传 `--force-resume`
|
||
- **THEN** 系统报错并列出 `source` 字段的变化,拒绝开始扫描
|
||
|
||
#### Scenario: 密码轮换
|
||
|
||
- **WHEN** 续跑时仅 `--source` 或 `--dest` 的密码与上次运行不同
|
||
- **THEN** 指纹一致,系统正常续跑
|
||
|
||
#### Scenario: 连接信息的存储形态
|
||
|
||
- **WHEN** 查看任意一次运行生成的 `state.json`
|
||
- **THEN** `config.source` 与 `config.dest` 为标准 MySQL DSN,且不包含密码明文
|
||
|
||
### Requirement: 一致性等级
|
||
|
||
文件输出的一致性等级 SHALL 为 at-least-once:崩溃后重跑可能向分片文件重复追加已处理的行,系统 MUST 在文档与启动输出中明确该行为。
|
||
|
||
#### Scenario: 崩溃后重跑
|
||
|
||
- **WHEN** 文件已写入但 checkpoint 尚未更新时进程崩溃,随后以相同配置重跑
|
||
- **THEN** 系统从上一个已提交游标继续,文件可能出现重复行,数据不丢失
|