1. 概要

PostgreSQL のソースコードデバッグとは、実行中のデータベースサーバープロセスにデバッガをアタッチし、1 つの SQL 文が parser、planner、executor を経て処理される流れをコードレベルで追跡する方法です。Mac 環境ではデフォルトのデバッガが lldb です。そこで、PostgreSQL をデバッグシンボル付きでビルドし、VSCode からバックエンドプロセスに attach できる環境を自分で構築してみました。

全体の流れは他の OS(Linux、Windows)と大きくは変わりませんが、Mac では gdb の代わりに lldb(Low Level Debugger、LLVM ベース)を使う必要があるため、一部の設定・コマンドに違いがあります。本記事の手順に沿って進めれば、次のことを自分で行えるようになります。

• PostgreSQL のソースコードをデバッグモードでビルドし、サーバーを起動する方法
• VSCode から lldb で PostgreSQL のバックエンドプロセスに Attach する方法
• breakpoint を設定し、クエリの実行フローをコードレベルで追跡する方法

2. PostgreSQL デバッグ環境の構築

2.1. PostgreSQL ソースコードの取得

PostgreSQL は GitHub に公式ミラーを提供していますが、実際のオリジナルソースは別のリポジトリで管理されています。そのため GitHub ではなく PostgreSQL 自身の Git リポジトリを利用する必要があります。

git clone https://git.postgresql.org/git/postgresql.git
cd postgresql

clone するとデフォルトの master ブランチになります。特定のバージョンをデバッグしたい場合は、該当ブランチ/コミットに checkout します。

## 17 버전 STABLE checkout
git checkout REL_17_STABLE && git pull
 
## 특정 마이너 버전 checkout
git checkout REL_17_6

2.2. PostgreSQL のビルド

ビルドに必要なパッケージをインストールします。

brew install icu4c
brew install pkg-config

PostgreSQL 公式のビルド手順に沿って、ビルド前に configure を実行します。

PG_VERSION=17
 
./configure \
	--prefix=$HOME/postgres/pg${PG_VERSION} \
	--enable-cassert \
	--enable-debug CFLAGS="-ggdb -O0 -fno-omit-frame-pointer" CPPFLAGS="-g -O0" \
	--with-includes=$(brew --prefix icu4c)/include \
	--with-libraries=$(brew --prefix icu4c)/lib \
	PKG_CONFIG_PATH=$(brew --prefix icu4c)/lib/pkgconfig

オプションの説明:

• --prefix: PostgreSQL のインストールパス
• --enable-cassert: 内部の C Assert 文を有効化
• --enable-debug: デバッグビルドを有効化
• CFLAGS: -ggdb(デバッグシンボル)、-O0(最適化の無効化)、-fno-omit-frame-pointer(スタックトレースを容易に)
• CPPFLAGS: -g(デバッグシンボル)
• --with-includes/--with-libraries: icu4c のヘッダ/ライブラリパス
• PKG_CONFIG_PATH: pkg-config のライブラリ探索パス

configure が終わると src/Makefile.global が生成されます。意図したオプション(特に -g、-O0)が反映されているか確認してください。抜けているとデバッグ中に変数の値が見えない問題が発生します(経験談です)。

grep -E '^(CFLAGS|CPPFLAGS) = ' src/Makefile.global

CPPFLAGS = -isysroot $(PG_SYSROOT) -g -O0  -I/opt/homebrew/opt/icu4c@77/include
CFLAGS = -Wall ... -g -ggdb -O0 -fno-omit-frame-pointer

これでビルドします。--prefix で指定した $HOME/postgres/pg17 に成果物が生成されます。

make && make install

2.3. PostgreSQL サーバーの起動

initdb で PGDATA(データディレクトリ)を作成します。

$HOME/postgres/pg17/bin/initdb -D $HOME/postgres/pgdata/pg17

サーバーを起動する前に、$HOME/postgres/pgdata/pg17/postgresql.conf で port、max_connections などの主要な設定を確認します。それではサーバーを起動して接続します。

$HOME/postgres/pg17/bin/pg_ctl -D $HOME/postgres/pgdata/pg17 -l $HOME/postgres/pgdata/pg17/logfile start
## waiting for server to start.... done / server started
 
$HOME/postgres/pg17/bin/createdb -p 5432 test
$HOME/postgres/pg17/bin/psql -p 5432 test

3. VSCode デバッグ環境の設定

VS Code のデバッガ設定はプロジェクトごと、またはグローバルに適用できます。本記事はグローバル設定を基準にします。

1. Command + Shift + P でコマンドパレットを開きます。
2. settings.json を検索して Preferences: Open User Settings (JSON) を選択します。

settings.json を開く

3. settings.json に以下を追加します。

"launch": {
  "version": "0.2.0",
  "configurations": [
    {
      "name": "(lldb) Attach DB - PostgreSQL 17",
      "type": "cppdbg",
      "request": "attach",
      "program": "${env:HOME}/postgres/pg${input:pg_version}/bin/postgres",
      "MIMode": "lldb"
    }
  ],
  "inputs": [
    {
      "id": "pg_version",
      "type": "promptString",
      "description": "Enter the PostgreSQL Version",
      "default": "17"
    }
  ]
}

4. サーバーに接続したら、SELECT pg_backend_pid(); でプロセスの PID を確認します。

SELECT pg_backend_pid();
 pg_backend_pid
----------------
          85770
(1 row)

5. fn + F5 または Run and Debug → (lldb) Attach DB - PostgreSQL 17 でデバッガを実行し、バージョンと pg_backend_pid の値を入力します。

lldb attach の実行

4. デバッグテスト

1. クエリ実行関数 exec_simple_query を src/backend/tcop/postgres.c で見つけて breakpoint を設定します。

exec_simple_query breakpoint

2. psql からクエリを実行します。

CREATE TABLE test(id bigint not null generated by default as identity, name text);

3. breakpoint が正常にトリガーされることを確認できます。ここからデバッグしながら PostgreSQL の動作原理をコードレベルで学習できます。

breakpoint がトリガーされて停止したデバッグ画面

5. まとめ

6. 参考文献

• PostgreSQL Git 저장소git.postgresql.org
• PostgreSQL 공식 문서 — Installation from Sourcepostgresql.org