설정

이 문서가 답하는 질문

• 확장 자체의 설정은 어디에 있고 어떻게 바꾸는가?
• 씨앗으로 들어 있는 설정 키 중 실제로 읽히는 것은 무엇인가?
• PostgreSQL 파라미터는 무엇을 어떻게 맞춰야 하는가?
• Studio와 Bolt 게이트웨이의 환경변수는?

1. 확장 설정 — og_catalog.setting

저장 위치와 형태

CREATE TABLE og_catalog.setting (
    key   text PRIMARY KEY,
    value text NOT NULL
);

(engine/sql/bootstrap.sql:252-255)

키·값 모두 text다. 타입 검증은 읽는 쪽에서 한다.

쓰기 — og_set_setting

SELECT og_set_setting('genai.enabled', 'on');

구현은 upsert 한 줄이다 (engine/src/compat/genai.rs:56-63):

INSERT INTO og_catalog.setting (key, value) VALUES ($1, $2)
ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value

실패 시 오류 문자열: failed to set '{key}': {e} (engine/src/compat/genai.rs:62).

읽기는 표준 SELECT로 한다:

SELECT key, value FROM og_catalog.setting ORDER BY key;

씨앗 키 4개 — 실측 평가

engine/sql/bootstrap.sql:256-260이 심는 값:

INSERT INTO og_catalog.setting (key, value) VALUES
    ('chunk_size',        '256'),
    ('supernode_threshold','4096'),
    ('inference_max_depth','16'),
    ('schema_version',    '1');

이 네 키를 코드가 실제로 읽는지 저장소 전체를 grep한 결과:

금지 (Forbidden): og_set_setting('chunk_size', '512') 같은 호출로 동작이 바뀔 것이라 기대하지 말 것. 아무 효과도 없다. 세그먼트 크기를 바꾸려면 engine/src/storage/adjacency.rs:15를 고치고 재빌드해야 한다. → 10_improvements_ops.md OPS-10

이 네 키는 백업 대상에서도 제외되어 있다 (engine/sql/bootstrap.sql:420-422), 확장 스크립트가 다시 심기 때문이다.

실제로 읽히는 설정 키 — genai.*

읽히는 유일한 설정군은 genai.vector.encode(= og_genai_encode)의 것이다. 읽는 함수는 setting() (engine/src/compat/genai.rs:43-51)이며, 빈 문자열은 미설정으로 취급한다.

설정 예 (모듈 주석 engine/src/compat/genai.rs:29-35에 있는 그대로):

SELECT og_set_setting('genai.enabled',  'on');
SELECT og_set_setting('genai.endpoint', 'http://localhost:11434/api/embed');
SELECT og_set_setting('genai.provider', 'ollama');
SELECT og_set_setting('genai.model',    'qwen3-embedding:latest');
SELECT og_set_setting('genai.dimensions', '1024');

운영 관점 경고: 이 함수는 PostgreSQL 백엔드가 직접 외부 HTTP 요청을 보낸다. engine/Cargo.toml:25-29의 주석이 명시하듯 블로킹 ureq 클라이언트이므로, 요청이 진행되는 동안 그 백엔드는 다른 질의를 처리하지 않는다. 기본이 비활성인 것은 의도된 설계다. 켤 때는 genai.timeout_ms를 함께 짧게 잡을 것. genai.dimensions를 2000 이하로 두는 것도 실무적으로 필요하다 — pgvector의 HNSW 인덱스가 2000차원에서 멈추기 때문이다 (engine/src/compat/genai.rs:155-159 주석).

히스토리 설정 키

og_enable_history(graph, type_name)은 트리거를 만들면서 history.<graph>.<type_name> 키를 'on'으로 기록한다 (engine/src/agent/mod.rs:462-467). 이 키는 기록용이며, 조회 경로가 이 값을 보고 분기하지는 않는다 — og_as_of는 og_data.og_history에 행이 있는지로 판단한다 (engine/src/agent/mod.rs:503-516).

-- 어떤 타입에 히스토리가 켜져 있는가
SELECT key, value FROM og_catalog.setting WHERE key LIKE 'history.%' ORDER BY key;

2. 에이전트 역할 — 세션 리소스 제한

og_create_role / og_apply_role은 세션에 리소스 제한을 거는 경로다 (engine/src/agent/mod.rs:405-441).

SELECT og_create_role('analyst', '{
  "statement_timeout_ms": 5000,
  "work_mem_kb": 65536,
  "read_only": true,
  "max_rows": 10000
}'::jsonb);

SELECT og_apply_role('analyst');

og_apply_role이 실제로 실행하는 SET (engine/src/agent/mod.rs:426-439):

og.max_rows 확인: engine/src/agent/mod.rs:438이 유일한 참조이며, current_setting('og.max_rows')를 호출하는 곳은 없다. → OPS-11

또한 네 개의 Spi::run(...)이 모두 .ok()로 끝나므로 SET 실패는 조용히 무시된다 (engine/src/agent/mod.rs:427,430,434,438).

존재하지 않는 역할을 적용하면: no agent role named '{name}' (engine/src/agent/mod.rs:424).

3. PostgreSQL 파라미터

아래 표에서 사실은 저장소에서 확인된 값이고, 권장은 그 사실로부터 도출한 판단이다. 저장소에는 postgresql.conf 템플릿이 없으므로 권장값에 근거 파일이 붙지 않는다.

사실 — 스토리지 레이아웃이 만드는 제약

권장 (판단)

pgrx 관리 인스턴스의 설정 파일을 고치려면 cargo pgrx가 만든 데이터 디렉터리의 postgresql.conf를 직접 수정한 뒤 재기동해야 한다. 저장소에는 그 경로가 명시되어 있지 않으므로 미확인이며, 다음으로 실측할 수 있다:

docker exec ontological-dev bash -lc \
  "psql -h localhost -p 28816 -d postgres -tAc 'SHOW config_file'"
docker exec ontological-dev bash -lc \
  "psql -h localhost -p 28816 -d postgres -tAc 'SHOW data_directory'"

세션 단위 설정은 postgresql.conf 없이도 즉시 확인·변경할 수 있다:

SHOW statement_timeout;
SHOW work_mem;
SHOW shared_buffers;
SET statement_timeout = '30s';

4. Studio 환경변수

portal/server/index.js:17-29가 읽는 전부:

변경 이력: 이 세 변수는 SEC-01/SEC-02 수정으로 추가되었다. 그 전에는 server.listen(PORT, cb) 가 모든 인터페이스에 바인드하면서 기동 로그는 http://localhost 라고 출력했고, POST /api/sql 에 게이트가 없었다.

풀 설정은 환경변수가 아니라 하드코딩되어 있다 (portal/server/index.js:27-28):

max: 8,
idleTimeoutMillis: 30_000,

운영 관점: 커넥션 8개가 상한이고 질의 타임아웃 설정이 없다. 장기 질의 8개가 동시에 걸리면 /api/health를 포함한 모든 엔드포인트가 대기한다. POST /api/sql은 임의 SQL을 그대로 풀에 넘긴다 (portal/server/index.js:296-308). → OPS-12

정적 파일은 portal/web/에서 서빙되며, 경로 탈출은 full.startsWith(WEB_DIR) 검사로 막는다 (portal/server/index.js:359-360).

OG_BENCH_DIR은 /^bench-(\d+)-(\d{8}T\d{6}Z)\.json$/ 패턴에 맞는 파일만 읽는다 (portal/server/index.js:91) — baseline.json은 리포트에 포함되지 않는다.

5. Bolt 게이트웨이 환경변수

설정 수단은 환경변수뿐이다 (bolt/src/main.rs:9 주석: "Configuration is environment only").

함정: OG_BOLT_PGPORT의 기본값 5432는 이 프로젝트의 실제 포트 28816과 다르다. 환경변수 없이 바이너리만 실행하면 엉뚱한 서버에 붙거나 붙지 못한다. start.sh:62가 이 값을 명시적으로 넘기는 이유다.

인증은 게이트웨이가 하지 않는다. HELLO의 user/password는 PostgreSQL 역할과 그 비밀번호 이며, 게이트웨이는 인증된 사용자 외의 누구로도 접속하지 않는다 (bolt/README.md:43, bolt/README.md:49-51). 따라서 RLS·권한·감사는 모두 PostgreSQL의 것이다.

TLS는 종단하지 않는다 — 앞단에 TLS 프록시를 두라고 명시되어 있다 (bolt/README.md:68).

기동 시 stderr로 한 줄을 남긴다 (bolt/src/main.rs:53-57):

ontological-bolt: listening on 0.0.0.0:7687, forwarding to postgres://localhost:28816/og (default graph 'default')

바인드 실패는 exit code 1 (bolt/src/main.rs:49-51):

ontological-bolt: cannot bind {listen}: {e}

금지 / 필수

금지 (Forbidden)

• 씨앗 설정 키 4종(chunk_size, supernode_threshold, inference_max_depth, schema_version)을 튜닝 노브로 취급하지 말 것 — 읽히지 않는다.
• og_apply_role의 max_rows를 행 수 제한으로 신뢰하지 말 것 — 읽히지 않는다.
• genai.endpoint를 신뢰할 수 없는 URL로 설정하지 말 것 — 백엔드가 그 URL로 직접 요청한다.
• Bolt 게이트웨이를 OG_BOLT_PGPORT 없이 기동하지 말 것.
• Studio를 공개망에 노출하지 말 것 — POST /api/sql이 임의 SQL 통로다.

필수 (Required)

• genai.*를 켤 때는 genai.timeout_ms를 반드시 함께 설정할 것.
• 세션 단위 가드레일이 필요하면 og_apply_role의 statement_timeout_ms / work_mem_kb / read_only 세 개만 쓸 것 (실효가 확인된 것).
• 설정 변경 후에는 SELECT key, value FROM og_catalog.setting ORDER BY key로 실제 반영을 확인할 것.