debugging
This guide walks through Turso's debugging toolkit for tracking down database problems. Compare bytecode between SQLite and Turso to pinpoint code generation bugs versus VM issues, enable trace logging for core components, run stress tests with ThreadSanitizer to catch threading problems, and use deterministic simulation with seeds to reproduce elusive bugs. Corruption debugging tools help diagnose WAL and integrity failures.
Debugging uses bytecode comparison, logging, ThreadSanitizer, and deterministic simulation to diagnose Turso database issues.
AI-generated summary based on this skill's SKILL.md
Install
tursodatabase/turso/debugging · repository language: Rust
git clone https://github.com/tursodatabase/turso
cp -r turso/.claude/skills/debugging ~/.claude/skills/debuggingFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to debug turso database issues effectively?
Debugging guides you through Turso's toolkit for tracking down database problems. Start by enabling trace logging with RUST_LOG to inspect core component behavior, then use bytecode comparison between SQLite and Turso to isolate code generation bugs from VM execution issues. For threading problems, run stress tests with ThreadSanitizer enabled. Deterministic simulation with seeds helps reproduce elusive bugs consistently.
What's the bytecode comparison method for SQLite vs Turso?
Debugging's bytecode comparison approach lets you diff the compiled instructions between SQLite and Turso to pinpoint where code generation diverges. This technique separates genuine VM execution bugs from incorrect query compilation. By comparing bytecode output for the same query, you can identify whether a problem stems from how Turso generates instructions or how it executes them.
How do I use ThreadSanitizer for turso stress testing?
Debugging recommends running stress tests with ThreadSanitizer enabled to catch threading bugs in Turso. ThreadSanitizer detects data races and synchronization issues that emerge under concurrent load. Combine this with stress testing to reproduce race conditions reliably, then use the sanitizer's output to locate the exact code paths causing threading problems.
How can deterministic simulation with seeds help debug turso?
Debugging supports deterministic simulation using seeds to reproduce elusive bugs consistently. By seeding the concurrent simulator, you lock in a specific execution order that triggered a failure, making it reproducible across test runs. This eliminates the randomness that makes threading and timing bugs hard to catch, letting you reliably trigger and fix the problem.
What tools does debugging provide for turso corruption analysis?
Debugging includes tools for analyzing database corruption and WAL integrity problems in Turso. These tools help diagnose storage layer failures and detect when write-ahead logs become corrupted. Use them alongside trace logging and bytecode comparison to understand whether corruption stems from code generation errors, VM bugs, or storage layer issues.
How do I trace turso query execution with RUST_LOG?
Debugging enables query execution tracing through RUST_LOG environment variable configuration. Set RUST_LOG to trace level to capture detailed logs from Turso's core components, parser, AST processing, and VM execution. This reveals the full path a query takes through the system, helping you spot where execution diverges from expected behavior or where performance degrades.
SKILL.md
rendered from the published skill — quoted content, verbatim
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;"
# 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 run
Threading 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 1000
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 3 files
.claude/skills/debugging/SKILL.md
.claude/skills/debugging/references/CORRUPTION-TOOLS.md
.claude/skills/debugging/scripts