debugging_skill

Overview

This skill teaches practical techniques to debug tursodb by comparing SQLite bytecode, using detailed logging, stress-testing threading with ThreadSanitizer, running deterministic simulations, and applying corruption analysis tools. It focuses on isolating whether a difference is in parsing, code generation, the VM, or the storage layer. The goal is to provide repeatable steps to reproduce, inspect, and fix bugs in a Rust-based, SQLite-compatible embedded database.

How this skill works

Start by EXPLAIN-ing the same SQL in SQLite and tursodb and compare bytecode to determine whether the discrepancy arises in code generation or execution/storage. Use structured logging at the core and targeted modules to capture execution traces. For concurrency bugs, run stress tests under ThreadSanitizer and reproduce race conditions with a deterministic simulator using seeds. For corruption or WAL issues, use the dedicated corruption debugging tools to inspect pages and WAL contents.

When to use it

• When query results differ between SQLite and tursodb and you need to locate the layer causing divergence
• When intermittent crashes or corrupt databases appear after concurrent workloads
• When a race condition or memory-safety issue is suspected
• When you need a repeatable reproduction for a subtle bug
• When validating fixes against SQLite behavior

Best practices

• Always EXPLAIN the same SQL in both SQLite and tursodb first to classify the issue as codegen vs VM/storage
• Enable targeted RUST_LOG traces rather than global trace to limit output size and focus on relevant components
• Use ThreadSanitizer on a nightly Rust toolchain for concurrency stress tests to surface data races
• Capture simulator seeds and test inputs to allow deterministic reproduction and easier bisecting
• When investigating corruption, take read-only snapshots of files and run corruption tools rather than modifying production data

Example use cases

• A SELECT returns different rows in tursodb than SQLite — use EXPLAIN to compare bytecode and trace VM execution
• Intermittent assertion failures under load — run stress tests with ThreadSanitizer to find races
• A database file fails integrity checks after a crash — run corruption analysis tools to locate damaged pages
• Non-deterministic test failures — rerun the simulator with the recorded seed to reproduce the scenario
• Performance regression suspected in code generation — compare generated bytecode sequences before and after changes