{#configuration-configuration}
# 설정

AgensGraph의 설정은 PostgreSQL의 설정에 자체 설정 열한 개를 더한 것입니다. 이 페이지는 설정하는
방법과 그래프 워크로드에 중요한 설정을 다룹니다. AgensGraph가 더한 설정은
[서버 설정](../reference/guc.md)을 참고하십시오. 이 페이지가 나열하지 않는 수백 개의 PostgreSQL
설정은 [PostgreSQL의 서버 설정 장](https://www.postgresql.org/docs/18/runtime-config.html)을
참고하십시오. 그대로 적용됩니다.

{#configuration-where-a-setting-can-be-set}
## 설정을 어디에 지정할 수 있는가

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

| 방법 | 범위 | 비고 |
| --- | --- | --- |
| `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`이며, 본디 세션별입니다. 모든 세션이 같은 그래프를
쓴다면 데이터베이스에 지정하십시오:

```sql
ALTER DATABASE mydb SET graph_path = moviekb;
```

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

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

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

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

{#configuration-memory}
## 메모리

이 넷이 서버 동작의 대부분을 좌우하며, 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로 두는 것이, 인덱스 스캔이 이길 상황에서 그래프 순회가
순차 스캔을 고르는 가장 흔한 이유입니다.

{#configuration-planner-settings-that-matter-for-traversal}
## 순회에 중요한 플래너 설정

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

{#configuration-asynchronous-io-on-postgresql-18}
## 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과 함께 빌드한
경우에만 쓸 수 있습니다. 설정하기 전에 확인하십시오:

```sql
SELECT enumvals FROM pg_settings WHERE name = 'io_method';
```

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

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

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

{#configuration-logging}
## 로깅

**`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
```

{#configuration-settings-agensgraph-adds}
## AgensGraph가 더하는 설정

열한 개이며 [서버 설정](../reference/guc.md)이 다룹니다.
`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()`는
  [그래프 메타데이터](../system_catalogs/graph-metadata.md)를 참고하십시오.
* **`enable_graph_dml`** 과 **`enable_graph_ddl`** — 기본으로 꺼져 있으며, SQL로 레이블에 쓰는
  것과 레이블의 모양을 바꾸는 것을 막습니다. 정비 작업이 아닐 때는 꺼 두십시오.
* **`eager_mem`** — eager 그래프 쓰기 계획이 `work_mem`과 별개로 쓸 수 있는 메모리입니다.

{#configuration-where-to-go-next}
## 다음에 볼 것

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