Debugging

tursodatabase/turso/.claude/skills/debugging

作者 tursodatabaseff97ec42cdef无许可证24K 个星标收录于 2026年10月9日更新于 2026年10月8日仓库今天更新

How to debug tursodb using Bytecode comparison, logging, ThreadSanitizer, deterministic simulation, and corruption analysis tools

仅含说明Software Development

AI 生成的概览

使用字节码对比、日志、模拟器和栈分析调试 tursodb 数据库引擎的指南。

功能: 该技能提供 tursodb 数据库引擎的调试指南。它描述了对比 SQLite 与 tursodb 字节码、手动检查查询、启用跟踪日志、运行 ThreadSanitizer 压力测试、用确定性模拟种子复现缺陷以及用脚本测量栈使用量的流程。它还指向损坏调试工具，以及涵盖解析器、代码生成器、虚拟机和存储层的架构参考。
适用场景: 在排查 tursodb 与 SQLite 的行为差异、诊断虚拟机或存储层缺陷、复现并发或线程问题，或分析 tursodb 的栈深度与数据库损坏时使用。
运行要求: 需要 Rust 工具链与 Cargo、tursodb 源码仓库，可选需要 nightly 工具链以进行 ThreadSanitizer 构建、sqlite3 用于字节码对比、lldb 用于栈分析。它附带 scripts/stack/ 下的 shell 脚本，以及 scripts 和 references/CORRUPTION-TOOLS.md 中引用的损坏调试工具。

Debugging Guide

Bytecode Comparison Flow

Turso aims for SQLite compatibility. When behavior differs:

1. EXPLAIN query in sqlite32. EXPLAIN query in tursodb3. Compare bytecode   ├─ Different → bug in code generation   └─ Same but results differ → bug in VM or storage layer

1. EXPLAIN query in sqlite32. EXPLAIN query in tursodb3. Compare bytecode   ├─ Different → bug in code generation   └─ Same but results differ → bug in VM or storage layer

Example

bash

# SQLitesqlite3 :memory: "EXPLAIN SELECT 1 + 1;"
# Tursocargo run --bin tursodb :memory: "EXPLAIN SELECT 1 + 1;"

# SQLitesqlite3 :memory: "EXPLAIN SELECT 1 + 1;"
# Tursocargo run --bin tursodb :memory: "EXPLAIN SELECT 1 + 1;"

Manual Query Inspection

bash

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

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

Logging

bash

# Trace core during testsRUST_LOG=none,turso_core=trace make test
# Output goes to testing/test.log# Warning: can be megabytes per test run

# Trace core during testsRUST_LOG=none,turso_core=trace make test
# Output goes to testing/test.log# Warning: can be megabytes per test run

Threading Issues

Use stress tests with ThreadSanitizer:

bash

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

rustup toolchain install nightlyrustup override set nightlycargo 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

# SimulatorRUST_LOG=limbo_sim=debug cargo run --bin limbo_sim -- -s <seed>
# Whopper (concurrent DST)SEED=1234 ./testing/concurrent-simulator/bin/run

# SimulatorRUST_LOG=limbo_sim=debug cargo run --bin limbo_sim -- -s <seed>
# Whopper (concurrent DST)SEED=1234 ./testing/concurrent-simulator/bin/run

Stack Usage

Parsing and translating an expression recurse once per level of nesting, so the stack frame size of those functions limits how deep an expression can be. Three scripts in scripts/stack/ measure stack use. Use a release build (cargo build --release --bin tursodb): debug builds do not reuse stack slots, so their frames say little about what users run. Run each script with -h for all options.

bash

# Frame size of each function, read from its prologue. -c compares two binaries.scripts/stack/frame-sizes.sh 'translate::expr::'scripts/stack/frame-sizes.sh -c /tmp/tursodb-main 'translate_expr$' 'parse_expr_inner$'
# Smallest stack that runs a SQL script, per binary. -S adds sqlite3.scripts/stack/min-stack.sh -S -b /tmp/tursodb-main -b target/release/tursodb deep.sql
# Which functions use the stack at the deepest point (runs under lldb).scripts/stack/stack-profile.sh deep.sql

# Frame size of each function, read from its prologue. -c compares two binaries.scripts/stack/frame-sizes.sh 'translate::expr::'scripts/stack/frame-sizes.sh -c /tmp/tursodb-main 'translate_expr$' 'parse_expr_inner$'
# Smallest stack that runs a SQL script, per binary. -S adds sqlite3.scripts/stack/min-stack.sh -S -b /tmp/tursodb-main -b target/release/tursodb deep.sql
# Which functions use the stack at the deepest point (runs under lldb).scripts/stack/stack-profile.sh deep.sql

Functions that recurse per level should be small. Move rare and large paths into #[inline(never)] helpers, like SQLite's SQLITE_NOINLINE.

Architecture Reference

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

Corruption Debugging

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

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

来源与署名

来源：tursodatabase/turso位于.claude/skills/debugging提交ff97ec4

许可证：无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

Debugging

Debugging Guide

Bytecode Comparison Flow

Example

Manual Query Inspection

Logging

Threading Issues

Deterministic Simulation

Stack Usage

Architecture Reference

Corruption Debugging

来源与署名

更多来自 tursodatabase/turso 的技能

Transaction Correctness

Storage Format

Testing

Index Knowledge

Mvcc

Differential Fuzzer

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices