SKILL.md
514 tokens · o200k_base · 1,914 bytes
Source excerpt starting at line 1.---name: debuggingdescription: 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 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;"``` ## Manual Query Inspection ```bashcargo 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``` ## Threading Issues Use stress tests with ThreadSanitizer: ```bashrustup 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``` ## 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](./scripts). See [references/CORRUPTION-TOOLS.md](./references/CORRUPTION-TOOLS.md) for detailed usage.
Discovery context
Discovered by repository scan. No exact path reference found in the snapshot’s root AGENTS.md.