기존 PostgreSQL 데이터에 그래프 검색을 더하는 pgGraph, 관계형 데이터의 그래프 탐색을 빠르게 만드는 방법

PostgreSQL을 사용하다 보면 관계형 데이터만으로는 답하기 까다로운 질문이 생깁니다. 예를 들어 특정 사용자와 두 단계 이내로 연결된 데이터를 찾거나, 한 사람과 특정 회사 사이의 최단 경로를 찾거나, 여러 테이블에 흩어진 관계를 한 번에 탐색해야 하는 경우입니다.

이런 작업은 기존 PostgreSQL에서도 재귀 SQL이나 복잡한 조인을 활용해 구현할 수 있지만, 스키마마다 별도의 쿼리를 구성해야 하고 반복적인 그래프 탐색에서는 성능 부담도 커질 수 있습니다.

pgGraph는 이 문제를 기존 PostgreSQL 데이터를 다른 저장소로 옮기는 방식이 아니라, 현재 사용하고 있는 PostgreSQL 테이블을 그대로 데이터의 기준점으로 유지하면서 그래프 탐색 기능을 추가하는 방식으로 접근합니다.

이 글에서는 pgGraph가 어떤 방식으로 PostgreSQL 테이블을 그래프로 활용하는지, 왜 빠른 그래프 탐색이 가능한지, PostgreSQL의 기존 기능과 어떻게 역할을 나누는지, 그리고 실제 설치와 실행은 어떻게 하는지 살펴보겠습니다.

반응형

pgGraph란 무엇인가

pgGraph는 PostgreSQL의 확장 기능으로, 일반적인 PostgreSQL 테이블을 대상으로 그래프 검색, 그래프 순회, 최단 경로, 관계형 질의를 수행할 수 있도록 합니다.

핵심은 기존 테이블을 그래프 전용 데이터베이스로 옮기지 않는다는 점입니다.

PostgreSQL 테이블은 계속해서 Source of Truth, 즉 원본 데이터의 기준으로 사용됩니다. pgGraph는 이 테이블에 정의된 관계를 바탕으로 파생된 그래프 인덱스를 만들고, graph 스키마에 제공되는 함수를 통해 SQL에서 그래프 질의를 실행합니다.

따라서 애플리케이션의 데이터와 기존 PostgreSQL 구조를 그대로 유지하면서 그래프 탐색이 필요한 부분을 추가할 수 있습니다.

대표적으로 다음과 같은 질문을 처리하는 데 사용할 수 있습니다.

• 특정 사용자와 2단계 이내로 연결된 레코드는 무엇인가?
• 특정 사람과 회사 사이의 최단 경로는 무엇인가?
• 등록된 여러 테이블을 대상으로 연결된 노드를 어떻게 검색할 수 있는가?

기존 PostgreSQL에서는 이런 질문을 처리하기 위해 스키마에 맞춘 재귀 SQL이나 반복적인 조인이 필요할 수 있습니다. pgGraph는 이러한 그래프 탐색을 별도의 그래프 데이터베이스나 새로운 쿼리 언어 없이 PostgreSQL 내부에서 수행할 수 있도록 합니다.

pgGraph의 핵심 구조는 '기존 데이터 + 파생 그래프 인덱스'

pgGraph를 이해할 때 중요한 부분은 PostgreSQL 테이블과 그래프 데이터의 관계입니다.

애플리케이션 데이터가 pgGraph로 이동하는 것이 아닙니다.

기존 PostgreSQL 테이블이 원본으로 남아 있고, pgGraph가 테이블 사이의 관계를 분석해 그래프 실행에 적합한 별도의 구조를 생성합니다.

이를 단순하게 표현하면 다음과 같은 구조입니다.

PostgreSQL 원본 테이블 → 관계 분석 → 파생 그래프 인덱스 → 그래프 탐색 실행

이 구조 덕분에 PostgreSQL은 계속해서 테이블 저장, WAL, MVCC, 내구성, 장애 복구 등을 담당합니다.

반면 pgGraph의 그래프 아티팩트는 원본 테이블에서 다시 생성할 수 있는 derived state, 즉 파생 상태입니다.

따라서 pgGraph는 PostgreSQL의 데이터 저장 기능을 대체하는 것이 아니라, 이미 존재하는 관계형 데이터에 그래프 실행 계층을 추가하는 방식이라고 볼 수 있습니다.

pgGraph가 그래프 탐색을 빠르게 처리하는 이유

pgGraph의 성능을 이해하려면 그래프 탐색 데이터를 어떻게 구성하는지 살펴볼 필요가 있습니다.

일반적인 그래프 탐색에서는 노드와 노드 사이의 연결 관계를 계속 찾아야 합니다. 관계형 데이터베이스에서는 이 과정에서 재귀 SQL이나 여러 번의 조인이 사용될 수 있습니다.

pgGraph는 이러한 반복적인 관계 탐색을 줄이기 위해 관계형 데이터를 그래프 탐색에 적합한 메모리 구조로 컴파일합니다.

CSR 기반 인접 관계 구성

pgGraph의 핵심 기술 가운데 하나는 CSR, 즉 Compressed Sparse Row 기반의 엣지 저장 구조입니다.

graph.build()가 관계 데이터를 컴파일하면 정방향과 역방향 CSR 엣지 저장소가 만들어집니다.

이 구조에서는 특정 노드의 이웃 노드가 연속적인 배열 영역에 저장됩니다.

따라서 탐색할 때마다 SQL을 통해 관계를 다시 찾아가는 대신, 그래프에 최적화된 메모리 영역을 직접 순회할 수 있습니다.

즉, 반복적인 관계 탐색에서 데이터베이스가 매번 관계를 재발견하는 작업을 줄이고, 이미 만들어진 그래프 구조를 활용해 탐색하는 방식입니다.

탐색 루프를 단순하고 빠르게 유지

SQL에서 pgGraph 함수를 호출하면 좌표, 라벨, 필터, 테넌트 범위 등의 조건을 먼저 확인합니다.

이후 실제 그래프 탐색 루프에 들어가면 CSR에 저장된 이웃 노드를 순회합니다.

이 과정에서 다음과 같은 정보를 활용합니다.

• 컴팩트한 u8 엣지 라벨 ID
• 타입이 지정된 FilterIndex
• 테넌트 비트맵
• 활성 상태 비트
• 동기화 오버레이

이처럼 그래프 탐색에 필요한 정보를 작은 구조로 구성해 반복적인 탐색 과정에서 효율적으로 활용할 수 있도록 설계되어 있습니다.

읽기 중심 환경을 고려한 그래프 아티팩트

pgGraph는 저장된 .pggraph 아티팩트를 원자적으로 기록합니다.

새로운 PostgreSQL 백엔드가 시작되면 아티팩트의 유효성을 확인한 뒤 변경되지 않는 정방향 그래프 배열과 해석 인덱스를 읽기 전용으로 매핑합니다.

이 구조에서는 운영체제의 페이지 캐시를 활용할 수 있습니다.

여러 개의 격리된 PostgreSQL 백엔드가 기본 그래프 데이터를 각자의 Rust 힙에 복사하는 대신, 동일한 물리 페이지를 공유할 수 있기 때문입니다.

여기서 중요한 점은 pgGraph의 아티팩트가 PostgreSQL의 버퍼 풀을 대체하는 것이 아니라는 것입니다.

PostgreSQL은 기존과 동일하게 테이블 저장소, WAL, MVCC, 내구성, 장애 복구를 담당합니다.

pgGraph의 아티팩트는 어디까지나 원본 PostgreSQL 테이블에서 다시 생성할 수 있는 파생 데이터입니다.

그래프 탐색의 안정성을 위한 안전장치

그래프 탐색에서 주의해야 할 부분 중 하나는 무제한으로 관계를 확장하는 작업입니다.

탐색 범위가 통제되지 않으면 데이터베이스의 메모리를 과도하게 사용할 수 있기 때문입니다.

pgGraph는 이러한 상황을 방지하기 위해 명시적인 회로 차단 장치를 제공합니다.

주요 기능은 다음과 같습니다.

• 탐색 깊이 제한
• 방문 노드 추적
• 프론티어 제한
• 페이지네이션
• 엄격한 OOM 및 메모리 보호

따라서 그래프를 무작정 확장하기보다 정해진 깊이와 범위 안에서 탐색하도록 제어할 수 있습니다.

이는 반복적인 그래프 검색에서 성능뿐 아니라 안정성을 확보하기 위한 중요한 요소입니다.

PostgreSQL은 계속 데이터의 기준으로 유지된다

pgGraph를 사용할 때 가장 중요한 특징 중 하나는 애플리케이션 데이터의 관리 방식이 바뀌지 않는다는 것입니다.

기존의 PostgreSQL 테이블, 제약조건, 인덱스, ACL, RLS, 백업, 애플리케이션의 데이터 쓰기 작업은 그대로 PostgreSQL의 영역에 남습니다.

pgGraph는 이 데이터를 복제해 새로운 시스템에서 관리하는 것이 아니라, 그래프 탐색을 위해 필요한 파생 상태를 구성합니다.

그래프 알고리즘은 내부 노드 인덱스를 대상으로 실행하고, 결과로 원본 테이블의 좌표를 반환하거나 필요한 경우 PostgreSQL의 원본 행을 즉시 가져옵니다.

또한 빌드, 동기화, VACUUM, 유지보수 작업도 SQL에서 호출할 수 있도록 구성되어 있습니다.

결국 데이터의 저장과 관리에 대한 책임은 PostgreSQL에 그대로 남고, pgGraph는 그 위에서 그래프 탐색을 담당하는 구조입니다.

pgGraph 설치와 빠른 실행

pgGraph는 Docker, Homebrew, PGXN, 소스 빌드 등 여러 방법으로 설치할 수 있습니다.

가장 간단하게 전체 Quickstart 데모를 실행하려면 Docker 기반 환경을 사용할 수 있습니다.

먼저 저장소를 내려받고 디렉터리로 이동합니다.

git clone https://github.com/evokoa/pggraph.git
cd pggraph

이후 Quickstart 스크립트를 실행합니다.

scripts/quickstart.sh

이 스크립트는 일회용 PostgreSQL 환경을 구성하고 데모 데이터를 로드한 뒤 그래프를 생성하고 예제 그래프 질의를 실행합니다.

Docker 또는 Docker Desktop이 실행 중이어야 합니다.

Windows에서는 Docker Desktop과 WSL2가 필요하며, 스크립트는 WSL2 또는 Git Bash에서 실행해야 합니다. 일반적인 PowerShell이나 Command Prompt용 스크립트는 아닙니다.

PostgreSQL 컨테이너에 설치하기

이미 실행 중인 PostgreSQL Docker 컨테이너에 pgGraph를 설치하는 방법도 제공됩니다.

scripts/quickstart.sh docker my-postgres 17 appdb postgres

이 명령을 사용하면 지정한 PostgreSQL Docker 컨테이너에 pgGraph를 설치할 수 있습니다.

로컬 PostgreSQL에 pgrx로 설치하기

소스에서 빌드해 로컬 PostgreSQL에 설치하는 방식도 사용할 수 있습니다.

scripts/quickstart.sh pgrx

pgGraph는 Rust/pgrx 기반 확장이기 때문에 소스 빌드에는 Rust 툴체인이 필요합니다.

설치된 확장 확인하기

Docker 기반 Quickstart를 실행했다면 컨테이너 내부에서 다음 명령으로 확장이 정상적으로 로드됐는지 확인할 수 있습니다.

docker exec pggraph psql -U postgres -d graph \
  -c "SELECT extname, extversion FROM pg_extension WHERE extname IN ('graph', 'pg_cron');"

로컬에 psql이 설치되어 있다면 직접 PostgreSQL에 접속할 수도 있습니다.

psql -h localhost -U postgres -d graph

pgGraph 설치가 완료된 뒤에는 PostgreSQL에서 다음과 같이 확장을 생성합니다.

CREATE EXTENSION graph;

그리고 다음 명령으로 설치된 버전을 확인할 수 있습니다.

SELECT extname, extversion
FROM pg_extension
WHERE extname = 'graph';

여기서 한 가지 기억해야 할 부분이 있습니다.

PGXN에서 사용하는 배포 이름은 pgGraph이지만 PostgreSQL에서 사용하는 확장 이름은 graph입니다.

따라서 실제 확장 생성 명령은 CREATE EXTENSION graph;입니다.

Homebrew를 이용한 설치

macOS 환경에서는 Evokoa Homebrew tap을 이용해 PostgreSQL 17용 pgGraph를 설치할 수 있습니다.

brew tap Evokoa/tap
brew install pggraph
brew test pggraph

PostgreSQL 서비스를 실행한 뒤 확장을 생성합니다.

brew services start postgresql@17
psql -d postgres -c "CREATE EXTENSION graph;"

설치된 확장을 확인하려면 다음 명령을 사용할 수 있습니다.

psql -d postgres -c "SELECT extname, extversion FROM pg_extension WHERE extname = 'graph';"

제공된 자료 기준으로 Homebrew formula는 서명된 릴리스 번들에서 pgGraph 1.0.0을 설치합니다.

PostgreSQL 버전 호환성 확인

pgGraph를 설치할 때는 PostgreSQL의 메이저 버전을 확인해야 합니다.

제공된 Docker 이미지는 PostgreSQL 14부터 18까지 제공됩니다.

PostgreSQL 메이저 버전이 명시되지 않은 1.0.0 및 latest 태그는 기본적으로 PostgreSQL 17 이미지를 사용합니다.

또한 확장 패키지의 PostgreSQL 메이저 버전은 대상 PostgreSQL 서버와 일치해야 합니다.

자료에서는 PostgreSQL 13을 공식 지원 대상에서 제외했다고 설명하고 있으며, pg13 pgrx 기능은 최선의 노력 방식으로 남아 있다고 안내합니다.

따라서 실제 설치 전에는 사용 중인 PostgreSQL 메이저 버전과 pgGraph 패키지의 버전을 맞추는 것이 중요합니다.

PGXN과 소스 코드로 설치하기

PGXN을 통한 설치도 가능합니다.

pgGraph는 Rust/pgrx 확장이므로 소스에서 빌드하려면 Rust 툴체인이 필요합니다.

필요한 주요 구성요소는 다음과 같습니다.

• PostgreSQL 개발 헤더 및 pg_config
• Rust toolchain 1.96
• cargo-pgrx 0.19.1

cargo-pgrx를 설치하려면 다음 명령을 사용할 수 있습니다.

cargo install cargo-pgrx --version 0.19.1 --locked

이후 현재 PostgreSQL의 메이저 버전을 확인하고 pgrx를 초기화합니다.

PG_MAJOR=$(pg_config --version | sed -E 's/[^0-9]*([0-9]+).*/\1/')
cargo pgrx init --pg${PG_MAJOR}="$(which pg_config)"

그리고 PGXN을 이용해 pgGraph를 설치합니다.

pgxn install pgGraph

직접 소스 코드를 내려받아 설치하는 방법도 있습니다.

git clone https://github.com/evokoa/pggraph.git
cd pggraph
make install
psql -d postgres -c "CREATE EXTENSION graph;"

여러 PostgreSQL 설치본을 사용하고 있다면 대상 서버의 pg_config를 명시할 수 있습니다.

export PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config
make install

make install 과정에서 sudo가 필요하다면 PG_CONFIG 환경 변수를 유지하도록 다음과 같이 실행할 수 있습니다.

sudo --preserve-env=PG_CONFIG make install

만약 postgres.h를 찾을 수 없다는 오류가 발생한다면 대상 PostgreSQL 메이저 버전에 맞는 PostgreSQL 서버 개발 패키지가 필요할 수 있습니다.

Quickstart에서 제공하는 실행 모드

pgGraph의 Quickstart 스크립트는 단순한 설치뿐 아니라 여러 실행 모드를 제공합니다.

기본 모드인 quickstart 또는 demo에서는 Docker PostgreSQL 서비스를 구성하고 데모 데이터를 로드한 뒤 예제 그래프 질의를 실행합니다.

setup 모드는 pgGraph가 설치된 PostgreSQL을 준비하지만 샘플 그래프는 로드하지 않습니다.

psql 모드는 데모 데이터를 준비한 후 psql을 실행합니다.

기존 Docker PostgreSQL에 설치하려면 다음 형태를 사용할 수 있습니다.

scripts/quickstart.sh docker CONTAINER [PG_MAJOR] [DB_NAME] [DB_USER]

로컬 PostgreSQL에 pgrx를 사용해 설치하려면 다음과 같이 실행합니다.

scripts/quickstart.sh pgrx [PG_MAJOR]

또한 Streamlit playground를 실행할 수도 있습니다.

scripts/quickstart.sh playground panama csr
scripts/quickstart.sh playground panama mutable

Playground는 사전 구성된 데이터셋과 projection mode를 사용해 pgGraph의 동작을 살펴볼 수 있도록 합니다.

Apache AGE와 pgGraph의 차이

pgGraph를 이해하려면 PostgreSQL에서 그래프 기능을 제공하는 다른 방식과 비교해보는 것도 도움이 됩니다.

자료에서는 Apache AGE와 pgGraph의 차이를 Storage Layer와 Execution Layer의 차이로 설명합니다.

Apache AGE는 PostgreSQL 내부에서 동작하는 property graph database입니다.

그래프 네임스페이스, vertex 및 edge 테이블, agtype, openCypher 등을 활용합니다.

반면 pgGraph는 기존 데이터 스키마를 그대로 유지합니다.

별도의 그래프 모델로 데이터를 옮기거나 Cypher를 새롭게 학습할 필요 없이 SQL 함수인 graph.search()나 graph.shortest_path()와 같은 기능을 이용해 기존 관계형 데이터에 그래프 탐색을 추가하는 방식입니다.

따라서 전용 property graph 모델이 필요하다면 AGE를 고려할 수 있고, 이미 존재하는 관계형 스키마를 유지하면서 제한된 범위의 고속 그래프 탐색을 추가하려는 경우 pgGraph의 접근 방식이 맞을 수 있습니다.

PostgreSQL 19 SQL/PGQ와는 어떻게 다른가

자료에서는 PostgreSQL 19의 SQL/PGQ와 pgGraph 역시 서로 다른 계층에서 동작한다고 설명합니다.

SQL:2023과 PostgreSQL 19에서는 CREATE PROPERTY GRAPH, GRAPH_TABLE 및 표준 그래프 패턴 매칭 기능을 제공하며, PostgreSQL의 플래너와 옵티마이저를 기반으로 그래프 패턴을 처리합니다.

즉 SQL/PGQ는 그래프 패턴을 표현하고 PostgreSQL의 옵티마이저가 실행 방법을 선택하는 접근입니다.

반면 pgGraph는 반복적으로 같은 그래프 구조를 탐색하는 상황을 대상으로 합니다.

특히 다음과 같은 조건을 가진 작업을 고려합니다.

• 반복적인 그래프 탐색
• 제한된 탐색 깊이
• 경로 제한
• 필터
• 테넌트 범위
• 애플리케이션 페이지네이션

pgGraph는 이러한 사용 패턴을 위해 CSR 인접 저장소와 다시 생성할 수 있는 그래프 아티팩트를 미리 구성합니다.

자료 기준으로 pgGraph 1.0의 PostgreSQL 14~18 지원 범위에서는 SQL/PGQ를 노출하지 않으며, PostgreSQL 19 통합은 별도의 공개 로드맵에서 추적되고 있습니다.

pgGraph가 의미하는 데이터 활용 방식

pgGraph의 가장 큰 특징은 기존 PostgreSQL을 버리고 새로운 그래프 데이터베이스를 도입하는 것이 아니라는 점입니다.

관계형 데이터는 계속 PostgreSQL에 저장합니다.

그리고 데이터 사이의 관계를 그래프 형태로 탐색해야 할 때 pgGraph가 그 역할을 담당합니다.

이를 통해 기존 데이터 관리 체계는 그대로 유지하면서 그래프 탐색이라는 새로운 사용 방식을 추가할 수 있습니다.

특히 반복적으로 같은 관계 구조를 탐색하면서도 탐색 깊이나 범위를 제한할 수 있는 환경에서는 pgGraph가 제공하는 CSR 기반의 그래프 실행 구조가 중요한 역할을 할 수 있습니다.

반대로 전용 property graph 모델 자체가 필요한 경우나 표준 그래프 패턴 매칭을 중심으로 사용하는 경우에는 자료에서 설명하는 Apache AGE 또는 PostgreSQL SQL/PGQ와 접근 방식이 달라질 수 있습니다.

따라서 중요한 것은 단순히 "어떤 그래프 기술이 더 좋은가"가 아니라, 현재 데이터가 어디에 있고 어떤 방식으로 그래프를 탐색하려는가를 먼저 판단하는 것입니다.

728x90

pgGraph는 기존 PostgreSQL 데이터를 그대로 유지하면서 그래프 검색과 탐색 기능을 추가할 수 있도록 설계된 PostgreSQL 확장입니다.

가장 중요한 특징은 PostgreSQL을 데이터의 기준으로 계속 사용한다는 것입니다.

애플리케이션의 원본 테이블과 제약조건, 인덱스, ACL, RLS, 백업, 데이터 쓰기 작업은 기존 PostgreSQL에서 처리하고, pgGraph는 그 데이터에서 파생된 그래프 인덱스를 구성해 그래프 탐색을 실행합니다.

특히 CSR 기반 인접 관계 저장, 메모리 중심의 그래프 탐색, 읽기 전용 아티팩트 매핑 등을 통해 반복적인 그래프 탐색을 효율적으로 처리하도록 설계되어 있습니다.

또한 탐색 깊이와 방문 노드, 프론티어, 페이지네이션, 메모리 사용량 등을 제어할 수 있는 안전장치를 제공해 무제한 그래프 확장으로 인한 위험도 줄일 수 있도록 구성되어 있습니다.

결국 pgGraph의 핵심은 "PostgreSQL을 버리지 않고 그래프 탐색 능력을 더하는 것"으로 정리할 수 있습니다.

이미 PostgreSQL을 중심으로 데이터를 관리하고 있고, 데이터 사이의 관계를 반복적으로 탐색하거나 최단 경로와 제한된 범위의 그래프 검색이 필요한 환경이라면 기존 데이터 구조를 크게 변경하지 않고 그래프 실행 계층을 추가할 수 있다는 점에서 의미가 있습니다.

앞으로 그래프 탐색이 필요한 애플리케이션에서 기존 관계형 데이터베이스와 그래프 처리 기술을 어떻게 결합할 것인지가 중요한 과제가 될 수 있습니다. pgGraph는 그 과정에서 PostgreSQL을 시스템 오브 레코드로 유지하면서 그래프 실행 성능을 보완하는 하나의 접근 방법을 제시합니다.

300x250

https://github.com/Evokoa/pgGraph

GitHub - Evokoa/pgGraph: Open-source graph database superpowers for your existing Postgres data.