DuckLake デバッグ備忘録

はじめに

duckdbのエクステンション、ducklakeをローカルで開発・デバッグする際の備忘録。

PRを出す際に探り探りでやっていたので、次回以降のために記録を残しておく。

参考資料

以下は一読すると良い:

• ducklakeのREADME
• duckdb公式Doc
  • Testing
    • SQLLogicTest の使い方が解説されているので一読すると良い
  • Internals
    • DuckLake のアーキテクチャやコンポーネントの説明がある

debug ビルドの作成

ducklakeをクローンして、git submoduleを初期化し、debugビルドを作成する:

git submodule update --init --recursive # 初回のみ
GEN=ninja make debug

差分を反映するには再ビルドが必要となるので、ソースを修正したらGEN=ninja make debug でデバッグビルドを更新する。

テスト実行

buildをすると、テストを実行できるプログラムが build/debug/test/unittest に生成される。

テストは以下のように実行する:

./build/debug/test/unittest test/sql/merge/merge_partition_update.test

• build/debug/test/unittest がデバッグビルドのテスト実行バイナリ。
• 引数に SQLLogicTest のテストファイルを指定して実行する。

より細かいテストの流し方

VSCode で デバッグ

launch.jsonを設定して、VSCodeのデバッガでDuckLakeのソースコードをステップ実行できるようにする。

記事を参考に作成:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "(lldb) test_simple_projection",
      "type": "cppdbg",
      "request": "launch",
      "program": "${workspaceFolder}/build/debug/test/unittest",
      "args": ["test/sql/merge/merge_partition_update.test"],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}",
      "MIMode": "lldb",
      "externalConsole": false
    }
  ]
}.vscode/launch.json

• program に build/debug/test/unittest を指定し、args で実行したい SQLLogicTest（例: test/sql/merge/merge_partition_update.test）を渡す。
• cwd はリポジトリのルートに設定しておく。
• これで VSCode のブレークポイントが DuckLake のソースにヒットするようになる。
  • 追いたいファイル（例: src/storage/ducklake_update.cpp）にブレークポイントを置く。
• 設定した launch.json で VSCode デバッガを起動し、テストを実行しながらステップ実行できる。

SQLテストは単スレッドで走らせるとデバッグしやすい。どうやらデフォルトでは並列スレッドで実行されるようなので、いちいちスレッドが切り替わってしまい、デバッグが困難になる。

• SQLogicTest の冒頭に PRAGMA threads=1; を追加し、並列実行を抑止する。
• デバッガで追いやすくなり、並列化によるログの混乱や競合を避けられる。