Debugging

tursodatabase/turso/.claude/skills/debugging

by tursodatabaseff97ec42cdefNo license24K starsListed Oct 9, 2026Updated Oct 8, 2026Repository updated today

How to debug tursodb using Bytecode comparison, logging, ThreadSanitizer, deterministic simulation, and corruption analysis tools

Instructions onlySoftware Development

AI-generated overview

Guide for debugging the tursodb database engine using bytecode comparison, logging, simulators and stack analysis.

What it does: This skill provides a debugging guide for the tursodb database engine. It describes workflows for comparing SQLite and tursodb bytecode, inspecting queries manually, enabling trace logging, running ThreadSanitizer stress tests, reproducing bugs with deterministic simulation seeds, and measuring stack usage with scripts. It also points to corruption debugging tools and an architecture reference covering the parser, code generator, virtual machine and storage layer.
When to use it: Use it when investigating behavioral differences between tursodb and SQLite, diagnosing VM or storage-layer bugs, reproducing concurrency or threading issues, or analyzing stack depth and database corruption in tursodb.
Requirements: Requires a Rust toolchain with Cargo, the tursodb source repository, and optionally a nightly toolchain for ThreadSanitizer builds, sqlite3 for bytecode comparison, and lldb for stack profiling. It ships shell scripts under scripts/stack/ and corruption tooling referenced in scripts and references/CORRUPTION-TOOLS.md.

Debugging Guide

Bytecode Comparison Flow

Turso aims for SQLite compatibility. When behavior differs:

1. EXPLAIN query in sqlite32. EXPLAIN query in tursodb3. Compare bytecode   ├─ Different → bug in code generation   └─ Same but results differ → bug in VM or storage layer

1. EXPLAIN query in sqlite32. EXPLAIN query in tursodb3. Compare bytecode   ├─ Different → bug in code generation   └─ Same but results differ → bug in VM or storage layer

Example

bash

# SQLitesqlite3 :memory: "EXPLAIN SELECT 1 + 1;"
# Tursocargo run --bin tursodb :memory: "EXPLAIN SELECT 1 + 1;"

# SQLitesqlite3 :memory: "EXPLAIN SELECT 1 + 1;"
# Tursocargo run --bin tursodb :memory: "EXPLAIN SELECT 1 + 1;"

Manual Query Inspection

bash

cargo run --bin tursodb :memory: 'SELECT * FROM foo;'cargo run --bin tursodb :memory: 'EXPLAIN SELECT * FROM foo;'

cargo run --bin tursodb :memory: 'SELECT * FROM foo;'cargo run --bin tursodb :memory: 'EXPLAIN SELECT * FROM foo;'

Logging

bash

# Trace core during testsRUST_LOG=none,turso_core=trace make test
# Output goes to testing/test.log# Warning: can be megabytes per test run

# Trace core during testsRUST_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:

bash

rustup toolchain install nightlyrustup override set nightlycargo run -Zbuild-std --target x86_64-unknown-linux-gnu \  -p turso_stress -- --vfs syscall --nr-threads 4 --nr-iterations 1000

rustup toolchain install nightlyrustup override set nightlycargo run -Zbuild-std --target x86_64-unknown-linux-gnu \  -p turso_stress -- --vfs syscall --nr-threads 4 --nr-iterations 1000

Deterministic Simulation

Reproduce bugs with seed. Note: simulator uses legacy "limbo" naming.

bash

# SimulatorRUST_LOG=limbo_sim=debug cargo run --bin limbo_sim -- -s <seed>
# Whopper (concurrent DST)SEED=1234 ./testing/concurrent-simulator/bin/run

# SimulatorRUST_LOG=limbo_sim=debug cargo run --bin limbo_sim -- -s <seed>
# Whopper (concurrent DST)SEED=1234 ./testing/concurrent-simulator/bin/run

Stack Usage

Parsing and translating an expression recurse once per level of nesting, so the stack frame size of those functions limits how deep an expression can be. Three scripts in scripts/stack/ measure stack use. Use a release build (cargo build --release --bin tursodb): debug builds do not reuse stack slots, so their frames say little about what users run. Run each script with -h for all options.

bash

# Frame size of each function, read from its prologue. -c compares two binaries.scripts/stack/frame-sizes.sh 'translate::expr::'scripts/stack/frame-sizes.sh -c /tmp/tursodb-main 'translate_expr$' 'parse_expr_inner$'
# Smallest stack that runs a SQL script, per binary. -S adds sqlite3.scripts/stack/min-stack.sh -S -b /tmp/tursodb-main -b target/release/tursodb deep.sql
# Which functions use the stack at the deepest point (runs under lldb).scripts/stack/stack-profile.sh deep.sql

# Frame size of each function, read from its prologue. -c compares two binaries.scripts/stack/frame-sizes.sh 'translate::expr::'scripts/stack/frame-sizes.sh -c /tmp/tursodb-main 'translate_expr$' 'parse_expr_inner$'
# Smallest stack that runs a SQL script, per binary. -S adds sqlite3.scripts/stack/min-stack.sh -S -b /tmp/tursodb-main -b target/release/tursodb deep.sql
# Which functions use the stack at the deepest point (runs under lldb).scripts/stack/stack-profile.sh deep.sql

Functions that recurse per level should be small. Move rare and large paths into #[inline(never)] helpers, like SQLite's SQLITE_NOINLINE.

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

Source and attribution

Source:tursodatabase/tursoin.claude/skills/debuggingat commitff97ec4

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Debugging

Debugging Guide

Bytecode Comparison Flow

Example

Manual Query Inspection

Logging

Threading Issues

Deterministic Simulation

Stack Usage

Architecture Reference

Corruption Debugging

Source and attribution

More from tursodatabase/turso

Transaction Correctness

Storage Format

Testing

Index Knowledge

Mvcc

Differential Fuzzer

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices