Debugging Guide
Bytecode Comparison Flow
Turso aims for SQLite compatibility. When behavior differs:
- EXPLAIN query in sqlite3
- EXPLAIN query in tursodb
- 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
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.