Files
archer/openspec/specs/archive-core/spec.md
T
voidandClaude Sonnet 4.6 bc4a6b504f Initial commit: archer, a Go-native MySQL/MariaDB table archiver
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>
2026-11-06 22:12:17 +08:00

178 lines
8.5 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.
# 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** 系统从上一个已提交游标继续,文件可能出现重复行,数据不丢失