# dm-database-parser-sqllog

## What This Is

高性能 Rust 库 `dm-database-parser-sqllog`，用于解析达梦数据库 SQL 日志文件。支持内存映射 I/O、零拷贝延迟解析、SIMD UTF-8 校验、memmem SIMD 混合边界检测、两阶段并行 RecordIndex、全字段可组合 FilterBuilder（56 个谓词方法）、以及 tokio async 可选接口。代码已按功能分层重组（parser/ filter/ async_api/ record.rs error.rs）。

v1.0 单线程吞吐 8.67 GiB/s（+35.5%），v1.1 完善 API 易用性并发布 crates.io，v2.0 完成代码现代化并添加全字段过滤与 async API。

## Core Value

在任意硬件上达到尽可能高的解析吞吐量（records/sec 和 GB/s），同时提供符合 Rust 生态习惯的易用 API。

## Current State: v2.0 Shipped

**Shipped:** 2026-05-23
**Version in Cargo.toml:** 2.0.0（待确认）

**What's available now:**
- 功能分层模块结构（parser/ filter/ async_api/ record.rs error.rs）
- FilterBuilder：56 个链式谓词方法，14 字段全覆盖，AND 语义组合
- AsyncLogParser：tokio optional feature，spawn_blocking 封装零拷贝路径
- 覆盖率 ≥90%，clippy 零警告，全量测试通过

## Requirements

### Validated

<details>
<summary>v1.0 — Performance Optimization</summary>

- ✓ 内存映射文件 I/O（`memmap2`）— v1.0
- ✓ 零拷贝 `Cow<'a, str>` 延迟字段解析 — v1.0
- ✓ SIMD UTF-8 校验（`simdutf8`）— v1.0
- ✓ 预构建 SIMD Finder（`memchr::memmem`）— v1.0
- ✓ 单线程迭代器 `iter()` — v1.0
- ✓ Rayon 并行迭代器 `par_iter()` — v1.0
- ✓ 延迟字段解析（`parse_performance_metrics` 等）— v1.0
- ✓ criterion benchmark：GB/s + records/sec 双维度 + 多行语料库 + metrics 变体 — v1.0 (MEAS-01/02/03)
- ✓ CI benchmark 回归门禁（baseline.json，5% 阈值）— v1.0 (MEAS-04)
- ✓ 全文件 head+tail 编码检测，消除 64 KB 截断 UB — v1.0 (CORR-01)
- ✓ Miri CI 覆盖 unsafe 解码路径 — v1.0 (CORR-02)
- ✓ find_indicators_split 验证守卫 + 边界测试 — v1.0 (CORR-03)
- ✓ `find_indicators_split` O(1) 早退 + 单次 memrchr — v1.0 (HOT-01/02)
- ✓ `#[inline(always)]` 热路径 + `#[cold]` 错误路径 + mmap Sequential — v1.0 (HOT-03/04)
- ✓ memmem SIMD 混合快速路径 + u64 掩码时间戳验证：+35.5% 单线程吞吐 — v1.0 (ALGO-01/02)
- ✓ RecordIndex + index() 两阶段并行 API，32 MB 阈值自动退化串行 — v1.0 (PAR-01/03)

</details>

<details>
<summary>v1.1 — API & Ergonomics</summary>

- ✓ ParseError 行号追踪 + skip_errors() 错误策略 — v1.1 (ERR-01/02/03)
- ✓ LogParserBuilder 链式 API（取代 LogParser::from_path）— v1.1 (API-01)
- ✓ filter_by_exec_time / filter_by_sql_contains 过滤方法 — v1.1 (API-02)
- ✓ exec_time() / row_count() 直接字段访问 — v1.1 (API-03)
- ✓ FromSqllog trait 自定义类型转换 — v1.1 (API-04)
- ✓ rustdoc 全覆盖（零 warning）— v1.1 (DOC-01)
- ✓ crate-level 3 个可运行 # Examples — v1.1 (DOC-02)
- ✓ examples/ 目录 2 个独立示例 — v1.1 (DOC-03)
- ✓ CHANGELOG.md v1.1.0（Keep a Changelog）— v1.1 (PUB-01)
- ✓ Cargo.toml 元数据完善（keywords 含 dameng）— v1.1 (PUB-02)
- ✓ README.md 6 节中文重写（安装 / Quick Start / 功能 / 性能 / API）— v1.1 (PUB-03)

</details>

<details>
<summary>v2.0 — Refactor, Filter & Async</summary>

- ✓ src/ 按功能重组为 parser/ filter/ async_api/ 子模块 + record.rs + error.rs — v2.0 (REFACTOR-01~05)
- ✓ lib.rs 顶层重导出所有公开类型，保持用户侧导入路径兼容 — v2.0 (REFACTOR-06)
- ✓ examples/ 和文档更新以反映新结构 — v2.0 (REFACTOR-07)
- ✓ FilterBuilder 14 字段全谓词（56 个公开方法），AND 语义组合 — v2.0 (FILTER-01~09)
- ✓ apply_filter / apply_filter_keep_errors 适配器 + LogIterator 委托方法 — v2.0 (FILTER-10)
- ✓ exec_time_gte / exec_time_gt 语义区分（历史兼容 + 精度保证）— v2.0 Phase 11
- ✓ AsyncLogParser + AsyncError（spawn_blocking 封装 mmap 同步路径）— v2.0 (ASYNC-01/02)
- ✓ tokio feature flag（`features = ["async"]`）：默认构建零 tokio 依赖 — v2.0 (ASYNC-03)
- ✓ with_filter / encoding_hint builder 方法 — v2.0 (ASYNC-04)

</details>

### Active

（所有 v2.0 requirements 已验证，等待下一里程碑定义新需求）

### Known Gaps

- ⚠ PAR-02 speedup ≥1.6x 目标未达（实测 1.01x）— Amdahl 定律限制。若需多线程加速，须重新设计工作负载

### Out of Scope

- 支持新日志格式 — 功能需求，不在优化范围
- GB18030 编码路径深度优化 — 场景罕见，收益不高
- 自定义 SIMD 换行扫描（packed_simd / std::simd）— `memchr` 已是天花板
- async/tokio 零拷贝方案 — Cow<'a> 生命周期无法跨 spawn_blocking；v2.0 改用 Vec<Sqllog<'static>> owned 方案
- 全局默认 mimalloc — 库 crate 不应强制用户分配器
- crate 名称简化（如 dm-sqllog）— 名称变更影响所有用户

## Context

- **v1.0 最终吞吐**：8.67 GiB/s 单线程（5 MB 合成语料库，含 20% 多行）
- **v2.0 代码量**：2,551 行 Rust（src/）
- **v2.0 变更规模**：66 文件，+9,832/-3,250 行，~30 commits
- **v2.0 里程碑**：3 阶段，6 计划，2026-05-21→23（3 天）
- **测试覆盖**：≥90% 行覆盖率（最终 90.65%），全量测试（含 async feature）通过
- **并行上限**：受 Amdahl 定律约束，par_iter() 在 8.4 GiB/s 吞吐下接近单核利用上限

## Constraints

- **Tech**: 纯 Rust
- **Correctness**: 所有现有测试必须通过，覆盖率 ≥ 90%
- **API**: 可以修改，但需兼顾库用户体验

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| 使用 mmap 而非 read | 零拷贝、OS 缓存友好 | ✓ Good |
| 延迟字段解析 | 只解析调用方需要的字段 | ✓ Good |
| SIMD Finder 静态预构建 | 避免每次调用重建 Finder | ✓ Good |
| Phase 顺序：Measurement first | 先建可信测量，后续优化有数据支撑 | ✓ Good |
| CORR-01: head+tail 全文件采样 | 消除大文件 GB18030 UB | ✓ Good |
| Phase 4 混合快速路径 | 纯 memmem 实测 -35%；单行记录需 memchr 快速路径 | ✓ 关键修正 |
| Phase 5 accept-as-is（PAR-02） | Amdahl 定律：index() 串行主导，并行无收益 | ✓ 有据可查 |
| v1.1 跳版到 1.1.0（不发 1.0.0） | v1.0 milestone 是内部优化，API 未稳定；v1.1 是第一个语义化版本 | ✓ Good |
| README 使用中文 | 达梦数据库用户主要是中文开发者 | ✓ Good |
| FilterBuilder Predicate 类型别名 | Box<dyn Fn(&Sqllog) -> bool + Send + Sync> 解决 clippy::type_complexity；'static 为 async 预留 | ✓ Good |
| exectime 不提供 eq，提供 gte/gt | f32 浮点精度问题，between 替代等值比较；gte 与历史 filter_by_exec_time 语义对齐 | ✓ Good |
| async 返回 Vec<Sqllog<'static>> | mmap 同步解析；spawn_blocking 内部需 owned 数据，Cow<'a> 无法跨线程 | ✓ Good |
| tokio 用 dep:tokio 而非 tokio/rt | Cargo 惯用写法，dev-dep 独立控制，语义等价 | ✓ Good |

## Evolution

**After each phase transition** (via `/gsd-transition`):
1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

**After each milestone** (via `/gsd-complete-milestone`):
1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state

---
*Last updated: 2026-05-23 after v2.0 milestone — Refactor, Filter & Async shipped*
