debugging
How to debug tursodb using Bytecode comparison, logging, ThreadSanitizer, deterministic simulation, and corruption analysis tools
- Installs
- 1.3K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/tursodatabase/turso --skill debugging- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads debugging automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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
Deterministic Simulation
Reproduce bugs with seed. Note: simulator uses legacy "limbo" naming.
# Simulator
RUST_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.
# 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.
FAQ
What does the debugging skill do?
How to debug tursodb using Bytecode comparison, logging, ThreadSanitizer, deterministic simulation, and corruption analysis tools
How do I install debugging?
Run npx skills add https://github.com/tursodatabase/turso --skill debugging in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/debugging/ (personal) or .claude/skills/debugging/ (project).
Which AI agents can use debugging?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is debugging safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains debugging?
It is published by tursodatabase in tursodatabase/turso. It has 1,314 recorded installs.
More from tursodatabase/turso
code-quality
tursodatabase/turso
General Correctness rules, Rust patterns, comments, avoiding over-engineering. When writing code always take these into account
index-knowledge
tursodatabase/turso
Generate hierarchical AGENTS.md knowledge base for a codebase. Creates root + complexity-scored subdirectory documentation.
async-io-model
tursodatabase/turso
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
testing
tursodatabase/turso
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
storage-format
tursodatabase/turso
SQLite file format, B-trees, pages, cells, overflow, freelist that is used in tursodb
pr-workflow
tursodatabase/turso
General guidelines for Commits, formatting, CI, dependencies, security
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.