debugging Skill

1---2name: debugging3description: How to debug tursodb using Bytecode comparison, logging, ThreadSanitizer, deterministic simulation, and corruption analysis tools4---5# Debugging Guide6 7## Bytecode Comparison Flow8 9Turso aims for SQLite compatibility. When behavior differs:10 11```121. EXPLAIN query in sqlite3132. EXPLAIN query in tursodb143. Compare bytecode15   ├─ Different → bug in code generation16   └─ Same but results differ → bug in VM or storage layer17```18 19### Example20 21```bash22# SQLite23sqlite3 :memory: "EXPLAIN SELECT 1 + 1;"24 25# Turso26cargo run --bin tursodb :memory: "EXPLAIN SELECT 1 + 1;"27```28 29## Manual Query Inspection30 31```bash32cargo run --bin tursodb :memory: 'SELECT * FROM foo;'33cargo run --bin tursodb :memory: 'EXPLAIN SELECT * FROM foo;'34```35 36## Logging37 38```bash39# Trace core during tests40RUST_LOG=none,turso_core=trace make test41 42# Output goes to testing/test.log43# Warning: can be megabytes per test run44```45 46## Threading Issues47 48Use stress tests with ThreadSanitizer:49 50```bash51rustup toolchain install nightly52rustup override set nightly53cargo run -Zbuild-std --target x86_64-unknown-linux-gnu \54  -p turso_stress -- --vfs syscall --nr-threads 4 --nr-iterations 100055```56 57## Deterministic Simulation58 59Reproduce bugs with seed. Note: simulator uses legacy "limbo" naming.60 61```bash62# Simulator63RUST_LOG=limbo_sim=debug cargo run --bin limbo_sim -- -s <seed>64 65# Whopper (concurrent DST)66SEED=1234 ./testing/concurrent-simulator/bin/run67```68 69## Architecture Reference70 71- **Parser** → AST from SQL strings72- **Code generator** → bytecode from AST73- **Virtual machine** → executes SQLite-compatible bytecode74- **Storage layer** → B-tree operations, paging75 76## Corruption Debugging77 78For WAL corruption and database integrity issues, use the corruption debug tools in [scripts](./scripts).79 80See [references/CORRUPTION-TOOLS.md](./references/CORRUPTION-TOOLS.md) for detailed usage.81