mcpField
D
debugging

debugging

github.com/tursodatabase開発25.1k1.3k 回インストール今日更新
リポジトリ

debugging について

Turso のデバッグガイドです。SQL の動作比較、ログ、並行テスト、決定的シミュレーション、スタック使用量の調査を扱います。プロジェクトのデータベースやランタイムの問題を調べる開発者向けです。

主な機能

  1. 01SQLite と Turso のバイトコード比較
  2. 02tursodb による SQL クエリの確認
  3. 03テスト中のコアログ追跡
  4. 04シードによる並行バグの再現
  5. 05スタック使用量の測定

活用シーン

  1. 01SQLite 互換クエリの動作差の特定
  2. 02スレッドやストレージ関連の障害調査
  3. 03深くネストした式のスタック制限確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/tursodatabase/turso --skill debugging

インストール後、Claude Code で/debuggingを入力して読み込まれたか確認します。

詳細

デバッグガイド

バイトコード比較の流れ

Turso は SQLite との互換性を目指しています。動作に違いがある場合：

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
例
# SQLite
sqlite3 :memory: "EXPLAIN SELECT 1 + 1;"

# Turso
cargo run --bin tursodb :memory: "EXPLAIN SELECT 1 + 1;"

クエリの手動検査

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

ロギング

# 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

スレッド関連の問題

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

決定論的シミュレーション

シードを指定してバグを再現します。注：シミュレーターでは従来の「limbo」という名前が使われています。

# Simulator
RUST_LOG=limbo_sim=debug cargo run --bin limbo_sim -- -s <seed>

# Whopper (concurrent DST)
SEED=1234 ./testing/concurrent-simulator/bin/run

スタック使用量

式の解析と変換では、ネストの各レベルで再帰するため、これらの関数のスタックフレームサイズによって、扱える式の深さが制限されます。scripts/stack/ にある3つのスクリプトでスタック使用量を測定できます。リリースビルド（cargo build --release --bin tursodb）を使用してください。デバッグビルドではスタックスロットが再利用されないため、そのフレームはユーザーが実行するビルドの実態をほとんど示しません。すべてのオプションを確認するには、各スクリプトを -h 付きで実行してください。

# 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

各レベルで再帰する関数は小さくしてください。まれにしか使われない大きな処理は、SQLite の SQLITE_NOINLINE のように、#[inline(never)] を付けたヘルパー関数に移動します。

アーキテクチャの概要

  • パーサー → SQL 文字列から AST を生成
  • コードジェネレーター → AST からバイトコードを生成
  • 仮想マシン → SQLite 互換のバイトコードを実行
  • ストレージ層 → B ツリー操作、ページング

破損のデバッグ

WAL の破損やデータベースの整合性に関する問題には、scripts にある破損デバッグツールを使用します。

詳しい使い方については、references/CORRUPTION-TOOLS.md を参照してください。

コメント

Markdown 対応