Agent Skills › glommer/pgmicro › debugging

debugging

GitHub

提供Turso数据库调试指南，涵盖字节码对比、日志追踪、线程竞争检测、确定性模拟及数据损坏分析。用于排查SQLite兼容性差异、VM错误及并发问题。

.claude/skills/debugging/SKILL.md glommer/pgmicro

Trigger Scenarios

排查SQL执行结果不一致定位数据库崩溃或数据损坏调试多线程并发问题复现随机性Bug

Install

npx skills add glommer/pgmicro --skill debugging -g -y

More Options

Non-standard path

npx skills add https://github.com/glommer/pgmicro/tree/master/.claude/skills/debugging -g -y

Use without installing

npx skills use glommer/pgmicro@debugging

指定 Agent (Claude Code)

npx skills add glommer/pgmicro --skill debugging -a claude-code -g -y

安装 repo 全部 skill

npx skills add glommer/pgmicro --all -g -y

预览 repo 内 skill

npx skills add glommer/pgmicro --list

SKILL.md

Frontmatter

{
    "name": "debugging",
    "description": "How to debug tursodb using Bytecode comparison, logging, ThreadSanitizer, deterministic simulation, and corruption analysis tools"
}

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