1. 개요

PostgreSQL 소스코드 디버깅은 실행 중인 데이터베이스 서버 프로세스에 디버거를 붙여, SQL 한 문장이 parser, planner, executor를 거쳐 처리되는 흐름을 코드 레벨에서 추적하는 방법입니다. Mac 환경에서는 기본 디버거가 lldb이므로, PostgreSQL을 디버그 심볼이 포함된 상태로 빌드하고 VSCode에서 백엔드 프로세스에 attach하는 설정이 핵심입니다.

전체 흐름은 다른 운영체제(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