debugging

tursodatabase/turso

Debug Turso database issues using bytecode comparison, logging, ThreadSanitizer, and deterministic simulation.

What is debugging?

Debugging guide for Turso (SQLite-compatible database) that covers bytecode comparison to identify code-generation vs. runtime bugs, logging with RUST_LOG, ThreadSanitizer for concurrency issues, and deterministic simulation to reproduce bugs with seeds.

Compare bytecode between SQLite and Turso to isolate bugs to code generation, VM, or storage layers
Enable trace-level logging of turso_core during test runs for detailed execution inspection
Run stress tests with ThreadSanitizer on nightly Rust to detect threading and race conditions
Reproduce bugs deterministically using seed-based simulation (limbo_sim and concurrent-simulator)
Inspect query execution plans and manual query results via EXPLAIN and direct cargo run commands
Debug WAL corruption and database integrity issues using dedicated corruption analysis tools

How to install debugging

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

Prerequisites

Rust toolchain (nightly for ThreadSanitizer builds)
Turso source code repository (tursodatabase/turso)
For ThreadSanitizer: x86_64-unknown-linux-gnu target installed

Claude Code

Cursor

Windsurf

Cline

How to use debugging

1.Run EXPLAIN on the same query in both sqlite3 and Turso to compare bytecode output
2.If bytecode differs, the bug is in code generation; if same but results differ, check VM or storage layer
3.Enable logging with RUST_LOG=none,turso_core=trace make test and check testing/test.log
4.For threading issues, install nightly and run cargo with ThreadSanitizer flags and stress test parameters
5.Use RUST_LOG=limbo_sim=debug cargo run --bin limbo_sim -- -s <seed> to reproduce bugs deterministically
6.Consult scripts/CORRUPTION-TOOLS.md for WAL and integrity debugging when database corruption is suspected

Use cases

Good for

Comparing EXPLAIN output between SQLite and Turso to identify where behavior diverges
Enabling detailed logging when a test fails to understand the execution flow
Running concurrent stress tests to catch race conditions and threading bugs before they reach production
Reproducing a reported bug by running the simulator with the same seed that triggered it
Analyzing database corruption or integrity violations using the provided corruption debug tools

Who it's for

Turso database developers and maintainers
Contributors debugging SQLite compatibility issues
Engineers investigating concurrency or threading problems in database operations
QA or support teams reproducing reported bugs with deterministic seeds

debugging FAQ

How do I know if a bug is in code generation or the runtime?

Compare EXPLAIN bytecode output between SQLite and Turso. If bytecode differs, the bug is in code generation. If bytecode is identical but results differ, the bug is in the VM or storage layer.

What does the RUST_LOG setting do?

RUST_LOG=none,turso_core=trace enables trace-level logging for turso_core during test runs, with output written to testing/test.log. Warning: output can be megabytes per test run.

How do I detect threading and race condition bugs?

Use ThreadSanitizer by installing nightly Rust, then run cargo with -Zbuild-std and the turso_stress binary with parameters like --nr-threads 4 --nr-iterations 1000.

Can I reproduce a bug that happened once?

Yes, use deterministic simulation with a seed. Run RUST_LOG=limbo_sim=debug cargo run --bin limbo_sim -- -s <seed> to reproduce the exact same execution path.

Where do I find tools for database corruption issues?

Corruption debugging tools are in the scripts/ directory. See references/CORRUPTION-TOOLS.md for detailed usage instructions.

Full instructions (SKILL.md)

Source of truth, from tursodatabase/turso.

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

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

Example

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

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

Manual Query Inspection

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

Logging

# Trace core during tests
RUST_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:

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.

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

# Whopper (concurrent DST)
SEED=1234 ./testing/concurrent-simulator/bin/run