SQL Benchmarks Lab

SQL 基准测试实验室

一个确定性、编排式测试框架，用于大规模验证数据库性能。 由 Ramona C. Truta 开发

---

使命：“真实基准”即代码

该平台是一个专门用于测试 SQL 性能假设的实验室。它将查询调优从凭直觉判断转变为可复现的科学。

系统的核心是一个确定性编排测试框架，它能保证：如果逻辑或环境发生变化，基准测试结果就会变化；如果二者都未变化，结果则可寻址并缓存。

范围：目前重点是合成数据和规范数据（TPC-H），这类数据适用于开展机制实验——通过受控、可复现的数据隔离待测变量。平台支持真实数据，但此功能仍属实验性质；有关合成数据与真实数据的选择依据、容器模型和路线图（AI 安全测试平台、真实数据信任链），请参阅 FAQ。

---

主要功能与创新

1. 上下文感知语义哈希（实验 ID）

系统的核心是实验 ID，这是一个 8 字符的哈希值，用于管理整个生命周期。该哈希是由以下内容生成的 SHA-256 指纹：

• 配置：YAML 中的每个维度（行数、偏斜度、参数）。
• SQL 逻辑：基准测试脚本的实际内容。
• 代码：所有与测量相关的 Python 代码——编排代码（assets/）、引擎客户端（resources/）和数据生成器（plugins/）。

语义规范化：哈希引擎会区分逻辑变更与格式变更。

• SQL：哈希前会规范化注释、空白字符和大小写。
• Python：编排脚本会被解析为抽象语法树（AST），以去除文档字符串和格式差异，确保只有在执行逻辑发生变化时，实验 ID 才会改变。

2. 多层冷缓存隔离

为确保内存缓冲区不会掩盖受 IO 限制的性能，我们采用双层冷启动机制：

• 进程外（Postgres）：每次查询前都必须重启 Docker 容器，以清除引擎级共享缓冲区。
• 全局 OS 刷新（mmap）：专用的 thrash_os_cache 基元会映射并写入一个匿名内存区域，其大小为可用 RAM 的一半，上限为 4 GB。每次测量前都会清除此区域，逐出 OS 页面缓存条目；此机制适用于容器化和进程内（DuckDB）引擎。

3. Agentic AI 集成

该平台面向自主工程的未来而构建。实验 ID 让 AI Agent 能够将实验室视为一个确定性性能 API。

• 完整的 Agentic 基准测试协议请参阅 AGENTS.md。

4. 声明式矩阵编排

基准测试以 YAML 中的 N 维矩阵形式定义。平台会将其展开为一组笛卡尔积形式的独立 Dagster 分区。这样便可并行分发任务，并进行细粒度重试。

---

使用与技术设置

前置条件

• uv：项目的 Python 环境与依赖管理器（快速、现代）。setup.sh 使用它，也可以用它为你安装 Python 3.11。
• Python 3.11+：核心运行环境（如果缺少，uv 会为你安装）。
• Docker：用于容器化引擎（Postgres、TypeDB），由测试框架自行管理——仅使用 DuckDB 的快速入门不需要 Docker。

安装与设置

从 PyPI 安装——实验室支持安装，可提供工具和 sqlbench CLI：

pip install sqlbenchdag

从源码安装——克隆代码仓库，以获取已发布的胶囊（sql_benchmarks/experiments/results/）和完整测试框架。实验室提供全面的设置脚本，用于管理虚拟环境、依赖项和目录初始化。

# 1. Automate Setup
chmod +x setup.sh && ./setup.sh

# 2. Activate Laboratory
source venv/bin/activate

执行工作流（CLI）

虽然系统由 Dagster 驱动，但主要的自动化工作流接口是 CLI。

# QUICKSTART: DuckDB only, no Docker required — runs in seconds
./run.sh sql_benchmarks/experiments/queue/quickstart.yaml --auto

# FULL BENCHMARK: Run all queued experiments (requires Docker for Postgres)
./run.sh queue --auto

# SINGLE EXPERIMENT: Pass a specific config path
./run.sh sql_benchmarks/experiments/queue/quack_execution_modes.yaml --auto

要编写自己的实验，请从带注释的模板开始，并查看 docs/experiments.md 中已发布运行的目录。

---

项目结构

通过严格区分 Harness 和 Scenario 进行管理：

/sql_benchmarks
├── /assets                 # THE HARNESS: Dagster factories & pipeline logic
├── /resources              # THE INFRASTRUCTURE: DB drivers & Docker management
├── /scripts/sql            # THE SCENARIOS: Raw SQL partitioned by scenario
├── /plugins                # THE DATA: Declarative generators & scenario providers
├── /utils                  # THE BRAIN: AST-hashing, common logic, & system primitives
└── /experiments            # THE LABORATORY
    ├── active.yaml         # LOCAL runtime staging — the coordinator overwrites
    │                       #   this on every run (gitignored; not shared state)
    ├── /queue              # Staging area for new experiment configs
    ├── /archive            # Library of previously defined experiment templates
    ├── /configs            # Registry of immutable, hash-addressed experiment capsules
    └── /results            # Data capsules: fragments, CSVs, and Dashboards

---

已发布的实验——Quack 调查

这是本实验室发布的首项研究：对 DuckDB Quack 客户端-服务端协议（测试版，v1.5.3）进行的独立测量。每一行都将可运行的配置链接到已提交且可验证的胶囊。完整数据、扩展指数和验证步骤见 docs/published_capsules.md。

阶段	问题	配置	胶囊	发现
I	协议开销有多大？	quack_execution_modes.yaml	b8e2bfaf	Attach 模式的开销随扫描规模增长（1000 万行时从 2.6× 增至 9.5×）；下推模式保持平稳，约为 2×。
II	为什么下推模式约为 2×，而不是 1×？	quack_residual_threads.yaml	25b0e134	剩余差异与服务端并行度降低有关（8 个线程中约有 2–4 个线程），而非传输开销。
III	这一结果对联接也成立吗？	tpch_quack_validation.yaml	b198363e	在经典 TPC-H Q3 上，下推模式的结果成立（约为 1.9×）；Attach 模式根本无法执行联接（DNF）。
IV	它能胜过现有方案吗？	quack_vs_postgres.yaml	902d1277	DuckDB-over-Quack（下推模式）比 PostgreSQL 快，最高达 13.2×，且差距随规模扩大。

阶段 0（b82b4eae）是开启这项调查的探索性侦察实验——详见 docs/published_capsules.md。

实验室还为其他研究提供了场景套件——selectivity/、 null_logic/、null_sentinel/、recursion/、sort_spill/、tpch/ 等， 位于 sql_benchmarks/scripts/sql/ 下；每套场景都可在引擎矩阵中运行。

---

命名与溯源

实验室在两个层面开展工作，分别采用不同的命名方式。区分二者，才能追溯数字，而不是只能盲目信任。

层级	含义	命名者	示例
实验胶囊	一次实验的完整结果	由机器分配的 Experiment ID——对问题（配置 + SQL + 测量代码）计算得到的 8 位 SHA-256	48c92f31
发布版本	支撑某项出版物的一组签名实验胶囊	人工命名：sqlbenchdag-<topic>-v<N>-<YYYYMMDD>	sqlbenchdag-quack-v1-20260614

一个发布版本包含多个实验胶囊；一个实验胶囊对应一次实验。机器为实验胶囊命名（使用无法伪造的哈希）；作者为发布版本命名（使用有意义的词语）。sqlbenchdag 是实验室的标识——sql + bench + dag（Dagster，即用于编排、使本实验室有别于单纯查询计时器的工具）。本实验室生成的每个发布版本都会带上这一标识。

两个哈希，各司其职（一个实验胶囊包含二者，它们并不相同）：

• Experiment ID（8 位）是一个地址——它为实验胶囊命名，同一个问题总会生成同一个地址；
• 完整性密封值（64 位，位于 integrity.seal）是一个校验和——用于验证实验胶囊的内容未被更改。归档时使用地址；密封值则是一个可检测篡改的封口。

可复现性以发布版本为准。 由于 Experiment ID 会对测量代码进行哈希，因此只有在代码修订版本固定时才稳定——而签名的发布标签恰好能将其锁定。要复现已发布的实验胶囊，请检出其发布标签并重新运行其配置；同一个问题会生成相同的 ID，否则比较会从机制上被拒绝。

溯源路线图：未来将为每个实验胶囊加上 generator 标记（sqlbenchdag@<commit>），记录生成该实验胶囊的确切构建版本。该标记由最终化代码写入，而最终化代码位于 Experiment ID 的哈希范围内，因此它会随未来的发布版本一同交付，而不会重新编号已发布的实验胶囊。

请参阅 docs/published_capsules.md，了解完整的信任链（可复现性、完整性、时间戳、作者身份）以及如何逐项验证。每次运行都会自动保证可复现性和完整性；时间戳和签名则是发布时才需添加的可选步骤——发布工作流见 docs/PUBLISHING.md。

---

许可证

版权所有 2025-2026 Ramona C. Truta。基于 Apache License 2.0 授权。

使用 Dagster、Polars、Docker、DuckDB 和 Postgres 构建。