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