Debugging

When your Turso queries aren't behaving like SQLite, this gives you the full debugging arsenal. The bytecode comparison workflow is the standout here: EXPLAIN your query in both engines, compare the output, and you'll know immediately if the bug is in code generation or deeper in the VM. Beyond that, you get ThreadSanitizer stress tests for concurrency bugs, deterministic simulation with seeds for reproducing flaky failures, and corruption analysis tools for WAL issues. The logging can dump megabytes per test run, so use it surgically. If you're working on database internals or chasing subtle compatibility issues, these tools will save you days of blind debugging.

skills.sh installs: 1.3K
GitHub stars: 25.2K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add tursodatabase/turso --skill debugging --agent claude-code

Installs into .claude/skills of the current project.

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 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