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>
60 lines
2.5 KiB
Markdown
60 lines
2.5 KiB
Markdown
# archer
|
|
|
|
`archer` 是一个 Go 原生的 MySQL/MariaDB 大表归档工具。它复用了 `pt-archiver`
|
|
的核心语义(按唯一索引 seek 分块、file + dest + purge 三件套),并补齐了
|
|
**可有序分片、可分段导入** 的导出能力。
|
|
|
|
导出的分片沿扫描顺序连续、有序、无重叠:可以按主键或时间戳范围并行导入,
|
|
也可以按日期目录分批处理。
|
|
|
|
## 特性
|
|
|
|
- 三种输出目标:文件分片、目标表、归档后删除源表行,可任意组合。
|
|
- 按唯一索引 seek 分块扫描,不依赖 `OFFSET`;日期模式按索引能力自动选择路径。
|
|
- 分片按扫描顺序编号,相邻分片主键范围连续、不重叠。
|
|
- `dump` / `csv` / `jsonl` 三种格式,`gzip` / `zstd` / `xz` 独立压缩。
|
|
- 原子封片、`manifest.jsonl` 清单、`state.json` 断点,支持中断续跑。
|
|
- `archer import` 按清单把归档重放进已存在的表:分片选择、SHA-256 预校验、幂等模式、`LOAD DATA` 与批量插入两种引擎。
|
|
- 实时进度、副本延迟等待、chunk 级重试。
|
|
|
|
## 快速开始
|
|
|
|
需要 Go 1.24+ 构建,MySQL 5.7+ / 8.0 或 MariaDB 10.x 运行;源表必须有主键或唯一索引。
|
|
|
|
```bash
|
|
go build -o archer ./cmd/archer
|
|
|
|
archer \
|
|
--source 'user:pass@tcp(10.0.0.5:3306)/app' \
|
|
--table orders \
|
|
--where "created_at < '2025-01-01'" \
|
|
--file ./export \
|
|
--format dump
|
|
```
|
|
|
|
需要时把归档按需装回一张已存在的同构表:
|
|
|
|
```bash
|
|
archer import \
|
|
--file ./export \
|
|
--dest 'user:pass@tcp(10.0.0.6:3306)/app' \
|
|
--dest-table orders \
|
|
--dry-run
|
|
```
|
|
|
|
更多示例、构建脚本与前置条件见[快速开始](docs/getting-started.md)。
|
|
|
|
## 文档
|
|
|
|
| 文档 | 内容 |
|
|
|---|---|
|
|
| [快速开始](docs/getting-started.md) | 环境要求、构建、最小示例 |
|
|
| [分片模式](docs/sharding.md) | `none`/`count`/`date`、日期分片、索引路径 A/B |
|
|
| [输出格式与导入](docs/output-formats.md) | `dump`/`csv`/`jsonl`、压缩、各数据库导入 |
|
|
| [导入归档](docs/import.md) | `archer import`:选片、完整性校验、两种引擎、列映射与幂等 |
|
|
| [清单、断点与一致性](docs/checkpoint-and-resume.md) | `manifest`、`state`、续跑、at-least-once |
|
|
| [进度显示](docs/progress.md) | 进度模式、阶段、总量估算口径 |
|
|
| [安全说明](docs/safety.md) | `--purge`、`--bulk-delete`、副本延迟等注意事项 |
|
|
| [CLI 参考](docs/cli-reference.md) | 全部参数、退出码、pt-archiver 对照 |
|
|
| [开发](docs/development.md) | 单元测试与集成测试 |
|