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
Decision gist · record as of 2026-07-28
Debugging uses bytecode comparison, logging, ThreadSanitizer, and deterministic simulation to diagnose Turso database issues. 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.
Use it when
- Debugging's bytecode comparison approach lets you diff the compiled instructions between SQLite and Turso to pinpoint where code generation.
- Debugging recommends running stress tests with ThreadSanitizer enabled to catch threading bugs in Turso.
Verify before relying
Read SKILL.md below before installing (3 files). Open directory: indexed for reading, not audited.
Install
tursodatabase/turso/debugging · repository language: Rust
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently 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)
File tree — 3 files
.claude/skills/debugging/SKILL.md
.claude/skills/debugging/references/CORRUPTION-TOOLS.md
.claude/skills/debugging/scripts
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Debug Turso database issues using bytecode comparison and logging”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
This guide breaks down how SQLite organizes data on disk, from the 100-byte header through page types, B-tree layouts, and cell formats. It covers record encoding with serial types, overflow page chains for large payloads, and freelist structures for space reuse. Includes Turso implementation details and debugging commands.
This skill documents Turso's experimental Multi-Version Concurrency Control system, which allows readers and writers to operate simultaneously without blocking through row-level snapshot isolation. It covers enabling MVCC via pragma, the versioning model tracking begin/end timestamps, and the architecture built on lock-free data structures. The guide also details checkpointing behavior, current limitations like garbage collection and recovery gaps, and testing patterns for MVCC-enabled code.
yield-injections provides test-only infrastructure for injecting cooperative yields and synthetic failures into resumable state machines. Use it to test state-machine re-entry safety, interleaving behavior, and abandonment cleanup by marking yield points and controlling when they fire. Includes fixed injectors for unit tests and simulator support for randomized deterministic coverage.
This guide explains Turso's Write-Ahead Logging system, covering how transactions are written, read, and checkpointed back to the main database file. It details the concurrency model where one writer coexists with multiple readers, checkpoint strategies from passive to truncate modes, and the recovery process after crashes. The guide also maps Turso's implementation to its core storage layer, distinguishing per-connection state from shared WAL structures.
CDC is Turso's change data capture system that records INSERT, UPDATE, and DELETE operations at the bytecode translation layer. Changes are written to a dedicated CDC table and consumed by the sync engine to replicate local modifications remotely. The system supports two schema versions and operates per-connection via PRAGMA configuration.
Turso is a Rust-based, in-process SQL database that runs SQLite-compatible queries in Node.js, browsers, React Native, and edge functions. It includes vector similarity search, full-text search powered by Tantivy, change tracking, encryption, and remote sync capabilities. This skill covers SDK setup, CLI usage, and recipes for all supported languages and platforms.
More skills memory-benchmark (MIT) · Performance (Apache-2.0) · code-quality (MIT)