Omnigraph 图数据库质量保障体系深度解析:GQT 逻辑测试语料与 DST 确定性仿真框架
Omnigraph 图数据库质量保障体系深度解析:GQT 逻辑测试语料与 DST 确定性仿真框架
Omnigraph 是一个面向对象存储的原生图数据库(graph database),支持分支工作流、类型化本体和多模态检索。正因为数据最终落在 S3/Azure 这类对象存储上,并发写入、崩溃恢复等场景才是它最容易出 Bug 的地方。Omnigraph 为此建了一套独特的质量保障体系:GQT 逻辑测试语料负责"每个行为都能被一个文本文件描述",DST 确定性仿真框架负责"任何故障都能被一键复现"。本文将带你完整看懂这套体系的设计思路与落地细节。
上面这张来自 RFC 0029 的参考架构图,直观说明了为什么质量保障必须"重投入":所有图数据、清单(manifest)和 Ledger 都存放在 Azure Blob Storage 的 az:// 集群根目录下,每一次写入都要经过准入租钥。对象存储路径上的崩溃窗口与并发交错,正是 Omnigraph 最难复现、也最危险的 Bug 温床。
为什么图数据库需要"重武器"级测试?
传统关系型数据库的测试难点在 SQL 语义;而 Omnigraph 作为对象存储原生图数据库,最大的风险来自三类场景:
- 崩溃恢复:一次写操作由多次持久化存储调用组成,中间任何一步断电/断网都会留下"半成品"状态;
- 并发交错:多个写入者同时对 manifest 做 CAS 竞争,时序稍有不同结果就不同;
- 隐性成本回归:RFC 0037 提到,曾经有一次"每个操作多出 55 次对象存储请求"的成本回归悄悄上线——因为墙钟基准测试把存储成本淹没在了方差里。
Omnigraph 的答案是两条腿走路:
| 层次 | 工具 | 回答的问题 |
|---|---|---|
| 行为正确性 | GQT 逻辑测试语料(.gqt 文件) |
查询、变更、分支合并的结果对不对? |
| 状态机正确性 | DST 确定性仿真(omnigraph-dst) |
崩溃、故障、并发下,状态机是否守住了不变量? |
两者的所有权划分写在 docs/dev/testing.md 中,核心原则是"在拥有该承诺的边界上测试"——查询行为归 GQT,机制断言、规模症状归 Rust 测试。
GQT 逻辑测试语料:一个文件 = 一个可执行的测试
📦 GQT(GQ Logic Test)语料位于 crates/omnigraph-gqt/,目前包含 330+ 个 .gqt 用例(cases/ 266 个、cases/v2/ 66 个,另有 2 个慢用例放在 cases_slow/ 由夜间工作流运行)。每个用例都是一个自包含的文本文件,格式规范定义在 RFC 0045 中。
一个 .gqt 文件长什么样?
以 branch_statement_lifecycle.gqt 为例,一个用例由若干节(section)组成:
# issue: none
# notes: Divergent writes merge; conflicting updates fail.
--- runner
timeout_ms: 10000
environments:
- target: omnigraph-engine
storage: local-filesystem
--- schema
node Person {
name: String @key
age: I32
}
--- seed
{"type":"Person","data":{"name":"alice","age":30}}
--- mutate
branch create b0
--- expect ok
结构一目了然:
--- runner:声明执行环境与超时(本地引擎、内存对象存储等);--- schema+--- seed:声明 Schema 和种子数据;--- query/--- mutate+--- expect:逐步操作并断言结果(行、受影响计数、错误信息);- 还支持
--- restart(重启后验证持久性)、循环、--- concurrent(并发块)、--- seam(故障注入点)。
回归测试的"文件锚点"约定
🧪 修复某个 issue 时,必须提交一个 issue_NNN_名称.gqt 用例,并在头部记录 red_on:(未修复构建上它必须是红的)。例如 issue_563_aggregate_uncapped.gqt 记录了"BM25 扫描窗口截断导致 count() 只数了 8 条而非 20 条"的回归。CI 会检查"关闭 issue 的 PR 必须携带同名回归用例",让回归测试从"靠自觉"变成"靠门禁"。
用例如何被发现与运行?
运行器 tests/gq_logic_tests.rs 用 datatest-stable 把 cases/ 下每一个 .gqt 递归注册成一个独立的 libtest 测试,因此:
- 新增用例不需要写一行 Rust;
- 可以用普通的名字过滤跑单个用例:
cargo test -p omnigraph-gqt --locked
cargo test -p omnigraph-gqt --test gq_logic_tests issue_563
- 每次调用都会在
target/gqt-artifacts/生成 JSON 报告,并打印--replay复现命令,冻结输入、断言证据和存储请求账本,保证"失败的证据本身可重放"。
DST 确定性仿真框架:让不可复现的故障变得可复现
🎲 DST(Deterministic Simulation Testing,代码在 crates/omnigraph-dst/,设计见 RFC 0037)是这套体系里最有想象力的一环。核心概念只有三个:
Scenario(规则)+ Seed(一个种子数)= Universe(一个完整的模拟生命周期)
关键在于:调度器平局裁决、ULID 身份生成、墙钟时间、工作负载、存储故障、崩溃时机——一切都由同一个根种子派生。这意味着重跑同一个 (scenario, seed) 对,今天和一年后会生成完全一致的"宇宙":相同的操作流、相同的 ID 与时间戳、相同的存储调用顺序、相同的最终存储状态。
这正是确定性买到的东西:可重复性。最罕见的崩溃和竞态,从此变成一条可以用种子复现的永久测试用例。据 RFC 0037 统计,框架上线第一周就在 8000+ 个宇宙中发现了 12 个问题(含 3 个公开 issue)。
五类预言机(Oracle)持续审判
仿真不只是"重放",每个宇宙都被 5 组预言机(共 22 个检测器,见 detector_census.txt)连续检查:
- 差分模型:人与边被镜像到
BTreeMap/BTreeSet中,每 3 步、最终重启后都必须与模型一致——同时兼任引用完整性预言机; - 双向崩溃契约:崩溃的操作必须是原子的(状态恰好等于模型,或模型+该操作),恢复只能前滚、绝不能回滚已提交的写;
- OCC 不变量:任意两个提交不能共享同一个
graph_commit_id; - 重放元测试:同一场景必须产生字节相等的
UniverseReport(含提交 ID 和完整查询的原始行序 JSON); - 守恒律:批量两语句转账必须保持余额总和不变。
三种互补的故障模型
| 故障模型 | 比喻 | 机制 |
|---|---|---|
| Fault plans | "天气" | 种子驱动的存储错误、延迟、丢失确认、文本损坏、有界陈旧 |
| Crash-window hunt | "狙击" | 在引擎编目的 72 个命名 failpoint(catalog::CRASH_WINDOWS)中,于种子选定的操作序号触发崩溃 |
| Crash-state enumeration | "地毯式搜索"(ALICE 式) | 对每个完成时刻 #k 都杀死一次进程,逐一对照精确世界模型 |
其中还有两条"送死通道":Lane A 是进程内模拟崩溃(存储包装器停止转发,同进程审判);Lane B 是真实死亡(父进程在 fsync 屏障行处等待到完成时刻 #k 后 SIGKILL 子进程,再从 oplog 恢复并审判)。
用确定性计数做性能回归
💡 由于一切可重放,"成本"也能被精确计数:仿真无法测墙钟,但可以精确数出每次操作的存储动作。cost_table.txt 就是一份提交进仓库的"金文件"(golden),例如:
AddFriend l.get calls=110
AddFriend l.list calls=16
AddFriend l.put calls=24
"merge 的 PUT 次数从 12 变成 17"从此是一个有名字的回归测试,而不是没人复核的数字。
如何亲手跑起来
# 完整 GQT 语料 + 运行器自测
cargo test -p omnigraph-gqt --locked
# DST 仿真套件(其目录下的 .cargo/config.toml 会注入所需环境变量)
cd crates/omnigraph-dst
cargo test
# 用失败日志里的种子精确复现
OMNIGRAPH_DST_SEEDS=17689751483034105621 cargo test dst_v11_parallel_seed_fleet
⚠️ 注意:DST 与 GQT 不在默认工作区测试命令中(cargo test --workspace --exclude omnigraph-gqt --exclude omnigraph-dst),它们需要独立的构建配置;完整的命令与 CI 门禁见 docs/dev/testing.md。
关键资料导航
| 你想了解… | 去看这里 |
|---|---|
| 测试所有权地图与规则 | docs/dev/testing.md |
| GQT 语料与运行器 | crates/omnigraph-gqt/ |
.gqt 格式合同 |
docs/rfcs/0045-gq-logic-tests.md |
| DST 仿真设计 | docs/rfcs/0037-deterministic-simulation-harness.md |
| DST 运行与故障轴 | crates/omnigraph-dst/README.md |
| 存储成本金文件 / 预言机清单 | cost_table.txt / detector_census.txt |
一句话总结:GQT 让"行为"变成可版本化的文本资产,DST 让"故障"变成可复现的坐标。当图数据库跑在对象存储之上,这种"每个断言有文件、每次失败有种子"的质量保障体系,就是把分布式复杂度关进笼子的方式。
