설정#

AgensGraph의 설정은 PostgreSQL의 설정에 자체 설정 열한 개를 더한 것입니다. 이 페이지는 설정하는 방법과 그래프 워크로드에 중요한 설정을 다룹니다. AgensGraph가 더한 설정은 서버 설정을 참고하십시오. 이 페이지가 나열하지 않는 수백 개의 PostgreSQL 설정은 PostgreSQL의 서버 설정 장을 참고하십시오. 그대로 적용됩니다.

설정을 어디에 지정할 수 있는가#

범위는 넓은 쪽에서 좁은 쪽 순이며, 적용되는 것 가운데 가장 좁은 범위가 이깁니다.

방법	범위	비고
`postgresql.conf`	클러스터 전체	파일을 고친 뒤 `ag_ctl reload` 를 합니다. context가 `postmaster`인 설정은 재기동해야 합니다.
`ALTER SYSTEM SET`	클러스터 전체	`postgresql.auto.conf`에 씁니다. 마찬가지로 reload나 재기동이 필요합니다.
`ALTER DATABASE db SET`	데이터베이스 하나	다음 접속부터 적용됩니다.
`ALTER ROLE r SET`	롤 하나	다음 접속부터 적용됩니다.
`SET`	현재 세션	접속을 끊으면 되돌아갑니다. `SET LOCAL`은 트랜잭션이 끝날 때 되돌아갑니다.

가장 먼저 만나게 될 설정은 graph_path이며, 본디 세션별입니다. 모든 세션이 같은 그래프를 쓴다면 데이터베이스에 지정하십시오:

ALTER DATABASE mydb SET graph_path = moviekb;

설정이 지금 무엇이고 그 값이 어디서 왔는지 보려면:

SELECT name, setting, source, sourcefile, sourceline
FROM pg_settings WHERE name = 'work_mem';

SHOW ALL은 전부를 나열합니다. pg_settings는 같은 정보를 걸러 볼 수 있는 테이블로 제공하므로 더 쓸모 있습니다. boot_val 컬럼은 내장 기본값이고, reset_val은 RESET 했을 때 얻는 값이며, context는 변경에 재기동이 필요한지 알려 줍니다.

참고

설정의 내장 기본값은 설치 디렉터리의 주석 처리된 postgresql.conf.sample이 아니라 pg_settings.boot_val에서 읽으십시오. boot_val이 서버가 실제로 기동할 때 쓰는 값입니다.

메모리#

이 넷이 서버 동작의 대부분을 좌우하며, PostgreSQL의 기본값은 어디서든 기동되도록 일부러 작게 잡혀 있습니다.

shared_buffers — 서버 자신의 페이지 캐시입니다. 기본값은 128 MB입니다. 전용 장비라면 RAM의 25%가 무난한 출발점입니다. 40%를 크게 넘기면 대개 역효과가 납니다. 운영체제의 캐시도 그 페이지들을 들고 있기 때문입니다. 재기동이 필요합니다.

work_mem — 정렬이나 해시 하나가 디스크로 넘기기 전에 쓸 수 있는 메모리 양입니다. 기본값은 4 MB입니다. 접속별이 아니라 연산별입니다. 그래프 쿼리는 해시를 여러 개 동시에 들고 있을 수 있고, 조인이 많은 쿼리는 이 값의 몇 배를 쓸 수 있습니다. 그러니 조금씩 올리고, 서버가 메모리를 소진하는지 지켜보십시오.

maintenance_work_mem — VACUUM·ANALYZE·CREATE INDEX·REINDEX를 위한 값입니다. 한 번에 명령 하나만 쓰므로, 대량 적재 뒤 인덱스를 만들 때 임시로 크게 올릴 만합니다.

effective_cache_size — 할당이 아니라 힌트입니다. 장비가 캐시에 쓸 수 있는 메모리가 대략 얼마인지 플래너에게 알려 줍니다. 그 추정이 인덱스 스캔을 감당할 만해 보이게 만듭니다. RAM의 50~75% 정도로 잡으십시오. 큰 장비에서 기본값 4 GB로 두는 것이, 인덱스 스캔이 이길 상황에서 그래프 순회가 순차 스캔을 고르는 가장 흔한 이유입니다.

순회에 중요한 플래너 설정#

random_page_cost — 임의 페이지 읽기를 순차 읽기에 견준 플래너의 추정값이며 기본값은 4입니다. 그 비율은 회전 디스크를 설명합니다. SSD나 NVMe에서 실제 비율은 1에 훨씬 가깝고, 그래프 순회는 거의 전부가 임의 접근입니다. 인덱스를 따라 흩어진 힙 페이지로 간선을 따라가기 때문입니다. 플래시 스토리지에서 이 값을 1.1 정도로 낮추는 것이 순회 계획을 좋게 만들 가능성이 가장 큰 단 하나의 변경입니다.

그 말을 곧이곧대로 믿지도, 극단까지 밀어붙이지도 마십시오. 재어 보십시오. 가장 느린 순회를 4일 때와 1.1일 때 EXPLAIN (ANALYZE, BUFFERS)로 돌려 비교하고, 자기 데이터에서 이기는 값을 쓰십시오. 0에 가까운 값은 임의 I/O가 공짜라고 플래너에게 말하는 것인데, 메모리 안에서도 사실이 아니며, 플래너는 기꺼이 스래싱하는 계획을 고를 것입니다.

max_parallel_workers_per_gather — 기본값 2입니다. 그래프 쓰기는 병렬로 실행되지 않고 순회는 대체로 직렬이므로, 이득의 대부분은 MATCH가 컴파일된 순차 스캔과 비트맵 스캔에서 옵니다. 이 값을 올리면 레이블 전체를 훑는 분석 쿼리에 도움이 됩니다.

jit — 기본으로 켜져 있습니다. 오래 도는 분석 쿼리에서는 제값을 하고, 짧은 쿼리에서는 컴파일 시간을 잡아먹습니다. 워크로드가 작은 순회의 연속이라면 꺼 놓고 재어 보십시오.

PostgreSQL 18의 비동기 I/O#

PostgreSQL 18은 비동기 I/O를 들여왔고, 그래프 쿼리도 그중 일부를 그냥 얻습니다. 이 이득이 쿼리 수정이 아니라 설정 변경에서 오므로 알아 둘 만합니다.

길이가 고정된 MATCH는 레이블 테이블에 대한 평범한 순차·비트맵·인덱스 스캔으로 컴파일되고, PostgreSQL 18의 미리 읽기는 순차 스캔과 비트맵 힙 스캔이 씁니다. 따라서 그것들은 저절로 이득을 봅니다. 그렇지 않은 것이 둘 있습니다. 평범한 인덱스 스캔의 힙 가져오기는 PostgreSQL 18에서 미리 읽기를 얻지 못하고, 가변 길이·최단 경로·데이크스트라 엔진은 설계상 정점을 하나씩 따라갑니다.

이를 제어하는 설정이 둘 있습니다:

effective_io_concurrency — PostgreSQL 18에서 기본값이 1에서 16으로 올랐습니다. 이 기법 전체의 관문이므로, 예전 릴리스의 postgresql.conf를 그대로 가져와 이 값을 1로 못 박아 두었다면 비동기 I/O를 꺼 놓은 것입니다.

io_method — 기본값은 worker이며, 읽기를 백그라운드 워커에서 수행합니다. Linux에서 차가운 스캔에는 io_uring이 더 빠르고 때로는 큰 차이가 나지만, 서버를 liburing과 함께 빌드한 경우에만 쓸 수 있습니다. 설정하기 전에 확인하십시오:

SELECT enumvals FROM pg_settings WHERE name = 'io_method';

 enumvals
---------------
 {sync,worker}

이 빌드에는 io_uring이 없습니다. 그것과 함께 빌드한 서버는 값 세 개를 나열합니다. io_method를 바꾸려면 재기동해야 합니다.

이득은 데이터가 캐시에 들어가지 않을 때 가장 크고, 들어갈 때는 거의 없습니다. 그러니 확인하려면 캐시가 차가운 상태에서 시험하십시오. 최단 경로 쿼리에는 도움을 기대하지 마십시오. 그것은 I/O가 아니라 직렬 탐색에 매여 있습니다.

로깅#

log_statement — 기본값은 none입니다. 2.18의 변경에 유의하십시오. 이제 mod가 Cypher 쓰기를 기록합니다. 2.18 이전에는 Cypher 문장이 all에서만 기록 대상이었으므로, 데이터를 바꾸는 문장을 남기라고 한 서버가 SQL INSERT는 남기고 그 옆의 CREATE는 조용히 건너뛰었습니다.

log_min_duration_statement — 그래프 워크로드가 느린데 어느 쿼리인지 모를 때 가장 먼저 살펴볼 설정입니다. 임계값을 넘는 모든 문장을 남기며, Cypher도 포함합니다.

auto_explain — contrib 모듈이며, 그래프 워크로드에서 가장 쓸모 있는 진단 수단입니다. 느린 순회는 대개 데이터가 늘어난 것이 아니라 계획이 바뀌었다는 뜻이기 때문입니다:

shared_preload_libraries = 'auto_explain'
auto_explain.log_min_duration = '3s'
auto_explain.log_analyze = on

AgensGraph가 더하는 설정#

열한 개이며 서버 설정이 다룹니다. allow_null_properties, auto_gather_graphmeta, cypher_allow_unsafe_ddl, eager_mem, enable_eager, enable_graph_ddl, enable_graph_dml, enable_graph_endpoint_elision, enable_multiple_update, enable_property_promotion, graph_path입니다.

운영에 관계되는 것은 다음과 같습니다:

graph_path — 세션이 작업하는 그래프입니다. 이것이 없으면 아무것도 해석되지 않습니다.
auto_gather_graphmeta — 플래너가 스캔을 쳐낼 수 있도록 ag_graphmeta를 최신으로 유지합니다. 쓰기마다 비용이 들므로 기본으로 꺼져 있습니다. 그 득실과 regather_graphmeta()는 그래프 메타데이터를 참고하십시오.
enable_graph_dml 과 enable_graph_ddl — 기본으로 꺼져 있으며, SQL로 레이블에 쓰는 것과 레이블의 모양을 바꾸는 것을 막습니다. 정비 작업이 아닐 때는 꺼 두십시오.
eager_mem — eager 그래프 쓰기 계획이 work_mem과 별개로 쓸 수 있는 메모리입니다.

다음에 볼 것#

배포 — 용량 산정, 데이터 디렉터리, systemd에서의 운영.
보안 — 인증, 롤, 그래프에 대한 권한.
쿼리 성능 — 계획을 상대로 하는 튜닝이며, 이 페이지와는 다른 문제입니다.