Debugging
Diagnose TursoDB/SQLite compatibility mismatches and reproduce concurrency or storage bugs while you ship edge SQLite workloads.
Overview
Turso debugging is an agent skill for the Operate phase that walks you through bytecode comparison, trace logging, ThreadSanitizer stress, and seeded simulation to isolate TursoDB bugs against SQLite-compatible behavior.
Install
npx skills add https://github.com/tursodatabase/turso --skill debuggingWhat is this skill?
- Bytecode comparison flow: EXPLAIN in sqlite3 vs tursodb to separate codegen from VM/storage bugs
- RUST_LOG=turso_core=trace logging during make test with output in testing/test.log
- ThreadSanitizer stress runs via turso_stress (--vfs syscall, configurable threads/iterations)
- Deterministic reproduction with limbo_sim seeds and concurrent Whopper simulator (SEED env)
- Architecture map from Parser through VM and storage for layer-targeted fixes
- 4-step bytecode comparison flow (EXPLAIN → compare → branch codegen vs VM/storage)
- ThreadSanitizer example: 4 threads and 1000 iterations
Adoption & trust: 739 installs on skills.sh; 19.1k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your Turso query returns different results than SQLite and you cannot tell whether codegen, the VM, or storage is wrong.
Who is it for?
Indie developers hacking on TursoDB or shipping apps where SQLite parity and Rust concurrency bugs must be proven, not guessed.
Skip if: Builders who only consume hosted Turso via SQL clients and never run the Rust repo, tests, or local tursodb binaries.
When should I use this skill?
When Turso behavior diverges from SQLite, tests fail intermittently under threads, or you need seeded simulation to reproduce a database bug.
What do I get? / Deliverables
You get a reproducible diagnosis path—matching or divergent bytecode, trace logs, sanitizer failures, or a deterministic seed—so fixes target the correct Turso layer.
- Documented reproduction (bytecode diff, log excerpt, or sim seed)
- Layer hypothesis (codegen, VM, or storage)
Recommended Skills
Journey fit
Production and pre-release Turso issues are triaged after code is running—bytecode diffs, stress sims, and corruption analysis belong in Operate errors, not greenfield build. The guide targets wrong query results, threading races, and corruption—classic error investigation rather than deploy or monitoring dashboards.
How it compares
Use instead of ad-hoc println debugging when you need SQLite EXPLAIN parity and Turso-specific stress or simulation tooling.
Common Questions / FAQ
Who is Turso debugging for?
Solo and small-team builders working in the TursoDB codebase or deeply debugging SQLite-compatible edge behavior in Rust, not casual SQL-only users.
When should I use Turso debugging?
Use it in Operate when query results disagree with SQLite, tests flake under concurrency, or you need a seeded sim replay; also during Ship testing when validating parity before release.
Is Turso debugging safe to install?
It is documentation for local cargo, nightly toolchains, and stress binaries—review the Security Audits panel on this page and treat stress commands as privileged local execution.
SKILL.md
READMESKILL.md - Debugging
# 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 ```bash # SQLite sqlite3 :memory: "EXPLAIN SELECT 1 + 1;" # Turso cargo 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;' ``` ## Logging ```bash # 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: ```bash 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. ```bash # 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](./scripts). See [references/CORRUPTION-TOOLS.md](./references/CORRUPTION-TOOLS.md) for detailed usage.