Turso差分模糊测试器：SQLite兼容性测试工具，发现数据库正确性错误

differential-fuzzer by tursodatabase/turso

385 周安装量

18,000 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/tursodatabase/turso --skill differential-fuzzer

数据库测试 Rust

🇨🇳中文介绍

差分模糊测试器

始终加载调试技能作为参考

差分模糊测试器通过比较 Turso 与 SQLite 对生成的 SQL 语句的执行结果，以发现正确性错误。

位置

testing/differential-oracle/fuzzer/

运行模糊测试器

单次运行

# 基本运行（100条语句，随机种子）
cargo run --bin differential_fuzzer

# 使用特定种子以确保可复现性
cargo run --bin differential_fuzzer -- --seed 12345

# 更多语句并启用详细输出
cargo run --bin differential_fuzzer -- -n 1000 --verbose

# 运行后保留数据库文件（用于调试）
cargo run --bin differential_fuzzer -- --seed 12345 --keep-files

# 所有选项
cargo run --bin differential_fuzzer -- \
  --seed <SEED>           # 确定性种子
  -n <NUM>                # 语句数量（默认：100）
  -t <NUM>                # 表数量（默认：2）
  -c <NUM>                # 每表列数（默认：5）
  --verbose               # 打印每条 SQL 语句
  --keep-files            # 将 .db 文件持久化到磁盘

持续模糊测试（循环模式）

# 使用随机种子无限运行
cargo run --bin differential_fuzzer -- loop

# 运行 50 次迭代
cargo run --bin differential_fuzzer -- loop 50

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

Docker 运行器（CI/生产环境）

# 从仓库根目录构建并运行
docker build -f testing/differential-oracle/fuzzer/docker-runner/Dockerfile -t fuzzer .
docker run -e GITHUB_TOKEN=xxx -e SLACK_WEBHOOK_URL=xxx fuzzer

docker-runner 的环境变量：

TIME_LIMIT_MINUTES - 总运行时间（默认：1440 = 24小时）
PER_RUN_TIMEOUT_SECONDS - 每次运行的超时时间（默认：1200 = 20分钟）
NUM_STATEMENTS - 每次运行的语句数（默认：1000）
LOG_TO_STDOUT - 打印模糊测试器输出（默认：false）
GITHUB_TOKEN - 用于自动提交问题
SLACK_WEBHOOK_URL - 用于通知

所有输出都位于 simulator-output/ 目录：

文件	描述
`test.sql`	所有已执行的 SQL 语句。失败的语句以 `-- FAILED:` 为前缀，错误的语句以 `-- ERROR:` 为前缀
`schema.json`	运行结束时（或失败时）的数据库模式
`test.db`	Turso 数据库文件（仅在 `--keep-files` 时存在）
`test-sqlite.db`	SQLite 数据库文件（仅在 `--keep-files` 时存在）

请始终遵循以下步骤

在错误输出中找到种子：

INFO: Starting differential_fuzzer with config: SimConfig { seed: 12345, ... }

使用该种子重新运行：

cargo run --bin differential_fuzzer -- --seed 12345 --verbose --keep-files

检查输出文件：
- simulator-output/test.sql - 找到失败的语句（查找 -- FAILED:）
- simulator-output/schema.json - 检查失败时的表结构
创建一个最小化的复现器
- 在 .sqltest 或 .rs 中创建复现器始终加载调试技能作为参考
手动比较行为：如果需要，尝试比较行为并最终生成报告。始终先使用 Edit 工具写入临时文件以测试 SQL，然后将其传递给二进制文件。
```
# 在 SQLite 上运行失败的 SQL
sqlite3 :memory: < simulator-output/test.sql

# 在 tursodb CLI 上运行
tursodb :memory: < simulator-output/test.sql
```

预言机失败类型

行集不匹配 - Turso 返回的行与 SQLite 不同
Turso 出错但 SQLite 成功 - Turso 拒绝了有效的 SQL
SQLite 出错但 Turso 成功 - Turso 接受了无效的 SQL
模式不匹配 - DDL 操作后表/列存在差异

警告（非致命）

无序 LIMIT 不匹配 - 没有 ORDER BY 的 LIMIT 可能返回不同的有效行

文件	用途
`main.rs`	CLI 解析，入口点
`runner.rs`	主模拟循环，在两个数据库上执行语句
`oracle.rs`	比较 Turso 与 SQLite 的结果
`schema.rs`	从两个数据库内省模式
`memory/`	用于确定性模拟的内存 IO

设置 RUST_LOG 以获取更详细的输出：

RUST_LOG=debug cargo run --bin differential_fuzzer -- --seed 12345

🇺🇸English

Differential Fuzzer

Always load Debugging skill for reference

The differential fuzzer compares Turso results against SQLite for generated SQL statements to find correctness bugs.

Location

testing/differential-oracle/fuzzer/

Running the Fuzzer

Single Run

# Basic run (100 statements, random seed)
cargo run --bin differential_fuzzer

# With specific seed for reproducibility
cargo run --bin differential_fuzzer -- --seed 12345

# More statements with verbose output
cargo run --bin differential_fuzzer -- -n 1000 --verbose

# Keep database files after run (for debugging)
cargo run --bin differential_fuzzer -- --seed 12345 --keep-files

# All options
cargo run --bin differential_fuzzer -- \
  --seed <SEED>           # Deterministic seed
  -n <NUM>                # Number of statements (default: 100)
  -t <NUM>                # Number of tables (default: 2)
  -c <NUM>                # Columns per table (default: 5)
  --verbose               # Print each SQL statement
  --keep-files            # Persist .db files to disk

Continuous Fuzzing (Loop Mode)

# Run forever with random seeds
cargo run --bin differential_fuzzer -- loop

# Run 50 iterations
cargo run --bin differential_fuzzer -- loop 50

Docker Runner (CI/Production)

# Build and run from repo root
docker build -f testing/differential-oracle/fuzzer/docker-runner/Dockerfile -t fuzzer .
docker run -e GITHUB_TOKEN=xxx -e SLACK_WEBHOOK_URL=xxx fuzzer

Environment variables for docker-runner:

TIME_LIMIT_MINUTES - Total runtime (default: 1440 = 24h)
PER_RUN_TIMEOUT_SECONDS - Per-run timeout (default: 1200 = 20min)
NUM_STATEMENTS - Statements per run (default: 1000)
LOG_TO_STDOUT - Print fuzzer output (default: false)
GITHUB_TOKEN - For auto-filing issues
SLACK_WEBHOOK_URL - For notifications

Output Files

All output goes to simulator-output/ directory:

File	Description
`test.sql`	All executed SQL statements. Failed statements prefixed with `-- FAILED:`, errors with `-- ERROR:`
`schema.json`	Database schema at end of run (or at failure)
`test.db`	Turso database file (only with `--keep-files`)
`test-sqlite.db`	SQLite database file (only with `--keep-files`)

Reproducing Errors

Always follow these steps

Find the seed in the error output:

INFO: Starting differential_fuzzer with config: SimConfig { seed: 12345, ... }

Re-run with that seed :

cargo run --bin differential_fuzzer -- --seed 12345 --verbose --keep-files

Check output files :
- simulator-output/test.sql - Find the failing statement (look for -- FAILED:)
- simulator-output/schema.json - Check table structure at failure time
Create a minimal reproducer
- Create reproducer in .sqltest or in .rs always load

Understanding Failures

Oracle Failure Types

Row set mismatch - Turso returned different rows than SQLite
Turso errored but SQLite succeeded - Turso rejected valid SQL
SQLite errored but Turso succeeded - Turso accepted invalid SQL
Schema mismatch - Tables/columns differ after DDL

Warning (non-fatal)

Unordered LIMIT mismatch - LIMIT without ORDER BY may return different valid rows

Key Source Files

File	Purpose
`main.rs`	CLI parsing, entry point
`runner.rs`	Main simulation loop, executes statements on both DBs
`oracle.rs`	Compares Turso vs SQLite results
`schema.rs`	Introspects schema from both databases
`memory/`	In-memory IO for deterministic simulation

Tracing

Set RUST_LOG for more detailed output:

RUST_LOG=debug cargo run --bin differential_fuzzer -- --seed 12345

Weekly Installs

368

Repository

tursodatabase/turso

GitHub Stars

17.9K

First Seen

Jan 28, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykPass

Installed on

claude-code290

github-copilot176

opencode110

codex110

gemini-cli110

cursor106

浏览器自动化专家指南：Playwright、Puppeteer、Selenium 最佳实践与反模式

3,100 周安装

Compare behavior manually : If needed try to compare the behaviour and produce a report in the end. Always write to a tmp file first with Edit tool to test the sql and then pass it to the binaries.

# Run failing SQL against SQLite
sqlite3 :memory: < simulator-output/test.sql

# Run against tursodb CLI
tursodb :memory: < simulator-output/test.sql