debugging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Debugging Guide

调试指南

Bytecode Comparison Flow

字节码对比流程

Turso aims for SQLite compatibility. When behavior differs:

1. EXPLAIN query in sqlite3
2. EXPLAIN query in tursodb
3. Compare bytecode
   ├─ Different → bug in code generation
   └─ Same but results differ → bug in VM or storage layer

Turso 力求与 SQLite 兼容。当行为出现差异时：

1. 在 sqlite3 中执行 EXPLAIN 查询
2. 在 tursodb 中执行 EXPLAIN 查询
3. 对比字节码
   ├─ 存在差异 → 代码生成环节存在 bug
   └─ 字节码相同但结果不同 → 虚拟机（VM）或存储层存在 bug

Example

示例

bash

undefined

bash

undefined

SQLite

sqlite3 :memory: "EXPLAIN SELECT 1 + 1;"

Turso

cargo run --bin tursodb :memory: "EXPLAIN SELECT 1 + 1;"

undefined

cargo run --bin tursodb :memory: "EXPLAIN SELECT 1 + 1;"

undefined

Manual Query Inspection

手动查询检查

bash

cargo run --bin tursodb :memory: 'SELECT * FROM foo;'
cargo run --bin tursodb :memory: 'EXPLAIN SELECT * FROM foo;'

bash

cargo run --bin tursodb :memory: 'SELECT * FROM foo;'
cargo run --bin tursodb :memory: 'EXPLAIN SELECT * FROM foo;'

Logging

日志

bash

undefined

bash

undefined

Trace core during tests

在测试期间追踪核心模块

RUST_LOG=none,turso_core=trace make test

Output goes to testing/test.log

输出内容会写入 testing/test.log

Warning: can be megabytes per test run

注意：每次测试运行可能会生成数兆字节的日志

undefined

undefined

Threading Issues

线程问题

Use stress tests with ThreadSanitizer:

bash

rustup toolchain install nightly
rustup override set nightly
cargo run -Zbuild-std --target x86_64-unknown-linux-gnu \
  -p turso_stress -- --vfs syscall --nr-threads 4 --nr-iterations 1000

使用 ThreadSanitizer 进行压力测试：

bash

rustup toolchain install nightly
rustup override set nightly
cargo run -Zbuild-std --target x86_64-unknown-linux-gnu \
  -p turso_stress -- --vfs syscall --nr-threads 4 --nr-iterations 1000

Deterministic Simulation

确定性模拟

Reproduce bugs with seed. Note: simulator uses legacy "limbo" naming.

bash

undefined

使用种子值复现 bug。注意：模拟器使用旧版的“limbo”命名。

bash

undefined

Simulator

模拟器

RUST_LOG=limbo_sim=debug cargo run --bin limbo_sim -- -s <seed>

Whopper (concurrent DST)

Whopper（并发DST）

SEED=1234 ./testing/concurrent-simulator/bin/run

undefined

SEED=1234 ./testing/concurrent-simulator/bin/run

undefined

Architecture Reference

架构参考

Parser → AST from SQL strings
Code generator → bytecode from AST
Virtual machine → executes SQLite-compatible bytecode
Storage layer → B-tree operations, paging

解析器 → 从 SQL 字符串生成 AST
代码生成器 → 从 AST 生成字节码
虚拟机 → 执行兼容 SQLite 的字节码
存储层 → B树操作、分页

Corruption Debugging

损坏调试

For WAL corruption and database integrity issues, use the corruption debug tools in scripts.

See references/CORRUPTION-TOOLS.md for detailed usage.

针对WAL损坏和数据库完整性问题，可使用 scripts 目录下的损坏调试工具。

详细使用方法请参阅 references/CORRUPTION-TOOLS.md。