Debugging
- 981 installs
- 23.5k repo stars
- Updated July 28, 2026
- tursodatabase/turso
debugging is a Turso database skill that walks developers through bytecode inspection, logging, sanitizers, and deterministic replay to resolve behavioral differences between Turso and SQLite.
About
debugging is a Turso project skill for systematically diagnosing when tursodb behavior diverges from SQLite. The documented workflow compares EXPLAIN bytecode between sqlite3 and cargo-run tursodb binaries, branching diagnosis toward code-generation bugs when bytecode differs or VM and storage-layer bugs when bytecode matches but results differ. The guide covers manual query inspection via cargo run --bin tursodb, ThreadSanitizer instrumentation, deterministic simulation, and corruption analysis tooling. Developers reach for debugging when migrating SQLite workloads to Turso, writing compatibility-sensitive SQL, or investigating query result mismatches in Rust-backed database development.
- Bytecode comparison workflow that isolates whether a divergence lives in codegen, VM, or storage
- ThreadSanitizer stress-test recipe for concurrent Rust code
- Deterministic simulation with seed-based replay using the limbo simulator
- Targeted logging commands that output to test.log without flooding the terminal
- Manual query inspection shortcuts for rapid EXPLAIN and SELECT validation
Debugging by the numbers
- 981 all-time installs (skills.sh)
- +46 installs in the week ending Jul 28, 2026 (Skillselion tracking)
- Ranked #48 of 610 Debugging skills by installs in the Skillselion catalog
- Security screen: MEDIUM risk (skills.sh audit)
- Data as of Jul 28, 2026 (Skillselion catalog sync)
npx skills add https://github.com/tursodatabase/turso --skill debuggingAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 981 |
|---|---|
| repo stars | ★ 23.5k |
| Security audit | 3 / 3 scanners passed |
| Last updated | July 28, 2026 |
| Repository | tursodatabase/turso ↗ |
How do you debug Turso versus SQLite query mismatches?
Systematically diagnose and resolve behavioral differences between Turso and SQLite using bytecode inspection, logging, sanitizers, and deterministic replay.
Who is it for?
Backend developers and database contributors debugging Turso compatibility issues against SQLite using Rust tooling and bytecode analysis.
Skip if: Developers using hosted Turso only through client SDKs who never run tursodb locally or touch the Rust engine source.
When should I use this skill?
A query or transaction returns different results or errors in Turso than in SQLite and local engine debugging is required.
What you get
Bytecode diff reports, sanitizer traces, deterministic replay logs, and a narrowed bug layer (codegen, VM, or storage).
- Bytecode diff analysis
- Sanitizer and replay diagnostic traces
By the numbers
- Documents a 3-step bytecode comparison flow: EXPLAIN in sqlite3, EXPLAIN in tursodb, then compare bytecode
Files
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 layerExample
# 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 runThreading 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 1000Deterministic 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/runArchitecture 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.
../../../../scripts/corruption-debug-tools/README.md
Related skills
Azure DiagnosticsSystematically diagnose and resolve production issues on Microsoft Azure using official Microsoft guidance.472k1.3kAzure MessagingQuickly diagnose and fix connection, authentication, and message-processing failures when using Azure Event Hubs or Service Bus SDKs.460k1.3k
Use My BrowserWhen their agent task requires access to the live browser session, rendered DOM state, authenticated dashboards, localhost apps, or DevTools-selected elements instea269k72
Diagnosing BugsGet a systematic, step-by-step process that surfaces the real root cause instead of guessing at bugs.222k183k
Systematic DebuggingFollow a repeatable four-phase process that forces root-cause discovery before any code changes.197k260k
Safe DebugGet conservative, non-destructive diagnosis of deep learning and agent errors before any code changes are made.161k507FAQ
How does Turso debugging isolate codegen bugs?
Turso debugging runs EXPLAIN on the same query in sqlite3 and tursodb via cargo run --bin tursodb. Different bytecode indicates a code-generation bug; identical bytecode with different results points to the VM or storage layer.
What tools does the Turso debugging skill cover?
The Turso debugging skill documents bytecode comparison, manual query inspection with cargo run, ThreadSanitizer, deterministic simulation, and corruption analysis for isolating engine-level failures.
Is Debugging safe to install?
skills.sh reports 3 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.