debugging
Debugging tools for Turso database using bytecode comparison, logging, and deterministic simulation.
- Bytecode comparison workflow identifies whether behavior differences stem from code generation bugs or VM/storage layer issues by comparing SQLite and Turso EXPLAIN output
- Logging via
RUST_LOGenvironment variable captures detailed traces from turso_core and simulator components during test runs - ThreadSanitizer stress tests detect threading issues across configurable thread counts and iteration counts
- Deterministic simulation with seed-based reproduction allows consistent bug recreation in both the simulator and concurrent DST (Whopper) environments
- Corruption analysis tools available in scripts directory for diagnosing WAL corruption and database integrity problems
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
# SQLite
sqlite3 :memory: "EXPLAIN SELECT 1 + 1;"
More from tursodatabase/turso
code-quality
General Correctness rules, Rust patterns, comments, avoiding over-engineering. When writing code always take these into account
1.0Kindex-knowledge
Generate hierarchical AGENTS.md knowledge base for a codebase. Creates root + complexity-scored subdirectory documentation.
657async-io-model
Explanations of common asynchronous patterns used in tursodb. Involves IOResult, state machines, re-entrancy pitfalls, CompletionGroup. Always use these patterns in `core` when doing anything IO
604storage-format
SQLite file format, B-trees, pages, cells, overflow, freelist that is used in tursodb
604testing
How to write tests, when to use each type of test, and how to run them. Contains information about conversion of `.test` to `.sqltest`, and how to write `.sqltest` and rust tests
598pr-workflow
General guidelines for Commits, formatting, CI, dependencies, security
596