PostgreSQL 19 pg_plan_advice 사용법과 성능 주의점은 네 단계와 몇 가지 위험으로 정리된다. 절차는 모듈 로드, EXPLAIN (PLAN_ADVICE)로 현재 플랜의 advice 문자열 생성, 고정할 요소만 골라 pg_plan_advice.advice에 설정, Supplied Plan Advice:의 피드백 확인 순서다. 이 기능은 PostgreSQL 19 이상에서만 쓸 수 있다.
위험도 분명하다. 데이터 분포가 바뀌었는데 advice가 플랜 조정을 막으면 나쁜 플랜이 고정된다. 적용할 수 없는 advice를 넣으면 advice가 없을 때보다 나쁜 플랜이 선택되기도 한다. query ID별 자동 적용을 맡는 pg_stash_advice는 플랜이 바뀌지 않아도 성능 비용을 낸다. 아래 내용은 2026-11-21에 확인한 PostgreSQL 19 공식 문서를 기준으로 한다.
목차
pg_plan_advice 적용 대상과 PostgreSQL 19 버전
PostgreSQL 19 릴리스 노트의 릴리스일은 2026-11-19다. Additional Modules 절에 두 항목이 함께 추가되었다.
pg_plan_advice모듈: 플래너 결정을 안정화하고 제어한다 (Robert Haas)pg_stash_advice확장: query ID별로 advice를 지정한다 (Robert Haas, Lukas Fittl)
같은 릴리스의 Source Code 절에는 planner_setup_hook, planner_shutdown_hook, joinrel_setup_hook, join_path_setup_hook 네 개의 훅 추가 항목도 있다.
pg_plan_advice 모듈 문서는 이 모듈을 특수 목적의 ‘plan advice’ 미니 언어로 주요 플래너 결정을 기술·재현·변경하는 도구로 설명한다. 용도는 둘이다. 좋다고 판단한 플랜을 안정화하는 것, 그리고 플래너가 비최적이라고 보는 플랜을 실험하는 것이다.
역할 분담은 이렇다. pg_plan_advice는 advice 문자열을 만들고 해석하며, 세션에 설정한 advice를 플래닝에 반영한다. 특정 query ID에 advice를 저장해 두고 자동으로 적용하는 일은 pg_stash_advice 몫이다.
시작 전 준비: 모듈 로드 방식 선택

문서의 Getting Started 절은 모듈 로드를 첫 단계로 둔다. 방법은 세 가지이며 적용 범위가 다르다.
| 로드 방법 | 반영 시점 | 적용 범위 |
|---|---|---|
shared_preload_libraries에 추가 |
서버 재시작 후 | 시스템 전체 |
session_preload_libraries에 추가 |
새 세션 시작 후 | 새로 연결하는 세션 |
LOAD 명령 |
실행 즉시 | 명령을 실행한 개별 세션 |
플랜 실험만 할 계획이라면 재시작이 필요 없는 세션 단위 로드로 충분하다. 문서는 LOAD 명령을 쓸 수 있다고만 적고 구체적인 구문 예제는 별도의 LOAD 명령 페이지로 넘긴다.
Getting Started 절은 로드 방법 세 가지만 기술하며, pg_plan_advice에 대해 `CREATE EXTENSION`을 실행하라는 언급은 없다. `pg_plan_advice.advice`를 설정하는 데 필요한 권한도 이 페이지에 적혀 있지 않다. 운영 환경에 넣기 전에 해당 부분은 따로 확인해야 한다.
pg_plan_advice 사용법: advice 생성에서 적용까지

공식 문서 예제는 join_fact(별칭 f)와 join_dim(별칭 d)을 f.dim_id = d.id로 조인한다. 아래 절차는 이 예제를 그대로 따른다.
1단계: EXPLAIN (PLAN_ADVICE)로 현재 플랜의 advice 생성
EXPLAIN에 PLAN_ADVICE 옵션을 붙이면 플래너가 고른 플랜이 advice 문자열로 출력된다. COSTS OFF는 비용 수치를 빼서 플랜 모양만 보기 위한 옵션이다.
EXPLAIN (COSTS OFF, PLAN_ADVICE)
SELECT * FROM join_fact f JOIN join_dim d ON f.dim_id = d.id;
QUERY PLAN
------------------------------------
Hash Join
Hash Cond: (f.dim_id = d.id)
-> Seq Scan on join_fact f
-> Hash
-> Seq Scan on join_dim d
Generated Plan Advice:
JOIN_ORDER(f d)
HASH_JOIN(d)
SEQ_SCAN(f d)
NO_GATHER(f d)
확인 방법은 Generated Plan Advice: 항목이 나왔는지 보는 것이다. 각 줄은 플랜의 한 가지 결정을 기술한다.
JOIN_ORDER(f d):f가 driving table이고 처음 조인하는 테이블이dHASH_JOIN(d):d가 hash join의 inner sideSEQ_SCAN(f d):f와d모두 sequential scanNO_GATHER(f d): 두 테이블 모두 Gather·Gather Merge 노드 아래에 오지 않음
2단계: 고정할 요소만 골라 pg_plan_advice.advice에 설정
advice 문자열은 시스템이 생성한 것을 써도 되고 직접 작성해도 된다. 문서가 권하는 방식은 생성된 문자열에서 강제하려는 요소만 골라 쓰는 것이다. 아래 예제는 조인 순서만 고정하고, 조인 방식과 스캔 방식은 플래너 판단에 맡긴다.
SET pg_plan_advice.advice = 'JOIN_ORDER(f d)';
EXPLAIN (COSTS OFF)
SELECT * FROM join_fact f JOIN join_dim d ON f.dim_id = d.id;
QUERY PLAN
------------------------------------
Hash Join
Hash Cond: (f.dim_id = d.id)
-> Seq Scan on join_fact f
-> Hash
-> Seq Scan on join_dim d
Supplied Plan Advice:
JOIN_ORDER(f d) /* matched */
두 번째 EXPLAIN에는 PLAN_ADVICE가 없다. 이 경우 advice 문자열은 새로 생성되지 않지만 Supplied Plan Advice:와 피드백은 계속 표시된다. 이 표시를 끄려면 pg_plan_advice.always_explain_supplied_advice를 false로 바꾼다. 기본값 true에서는 항상 보이고, false면 EXPLAIN (PLAN_ADVICE)일 때만 나온다.
설정 단계의 확인 방법은 Supplied Plan Advice: 아래에 방금 넣은 문자열이 그대로 찍히는지 보는 것이다.
advice 태그와 target 문법
Generated Plan Advice:에 나오는 태그는 문서 F.30.4에서 범주별로 나뉜다.
| 범주 | 태그 |
|---|---|
| Scan Method | SEQ_SCAN, TID_SCAN, INDEX_SCAN, INDEX_ONLY_SCAN, FOREIGN_JOIN, BITMAP_HEAP_SCAN, DO_NOT_SCAN |
| Join Order | JOIN_ORDER |
| Join Method | MERGE_JOIN_MATERIALIZE, MERGE_JOIN_PLAIN, NESTED_LOOP_MATERIALIZE, NESTED_LOOP_MEMOIZE, NESTED_LOOP_PLAIN, HASH_JOIN |
| Partitionwise | PARTITIONWISE |
| Semijoin Uniqueness | SEMIJOIN_UNIQUE, SEMIJOIN_NON_UNIQUE |
| Parallel Query | GATHER, GATHER_MERGE, NO_GATHER |
괄호 안의 f, d는 advice target이다. target은 쿼리에 관여한 특정 relation 인스턴스를 고유하게 식별하며, 단순한 쿼리에서는 relation alias 하나로 충분하다. 서브쿼리, 파티션 테이블, 같은 alias의 중복 언급이 있으면 일반 문법이 쓰인다.
alias_name#occurrence_number/partition_schema.partition_name@plan_name
alias_name 외 요소는 필요할 때만 붙이고, 생략하면 앞의 구두점도 함께 뺀다. 파티션 자식을 가리킬 때는 partition schema와 partition name이 반드시 들어간다. plan name은 최상위 플랜에서는 생략하고 서브플랜에서는 반드시 넣는다. 문서가 권하는 target 확인 방법은 직접 조합하는 대신 1단계의 EXPLAIN (PLAN_ADVICE) 출력을 복사하는 것이다.
적용 결과 확인: matched와 Disabled 플랜 구분
advice를 넣은 뒤의 판단 기준은 Supplied Plan Advice: 줄 끝의 피드백 주석이다. 앞 예제의 /* matched */는 f와 d가 쿼리에서 발견되었고 결과 플랜이 advice를 따른다는 의미다.
matched가 아닌 피드백이 붙으면 플랜 본문을 다시 읽어야 한다. 문서의 반례는 존재하지 않는 테이블 x를 조인 순서 맨 앞에 넣은 경우다.
SET pg_plan_advice.advice = 'JOIN_ORDER(x f d)';
EXPLAIN (COSTS OFF)
SELECT * FROM join_fact f JOIN join_dim d ON f.dim_id = d.id;
QUERY PLAN
----------------------------------------------------
Nested Loop
Disabled: true
-> Seq Scan on join_fact f
-> Index Scan using join_dim_pkey on join_dim d
Index Cond: (id = f.dim_id)
Supplied Plan Advice:
JOIN_ORDER(x f d) /* partially matched */
JOIN_ORDER(x f d)에서는 f와 d 모두 첫 테이블이 아니다. 플래너는 x와의 조인이 먼저라고 보고 두 테이블 간 직접 조인을 모두 비활성화한다. 플래닝은 실패할 수 없으므로 Disabled: true가 붙은 플랜이 선택된다.
두 출력을 나란히 놓으면 플랜 차이가 드러난다.
| advice | 최상위 노드 | d 스캔 |
피드백 |
|---|---|---|---|
| 없음 (1단계) | Hash Join | Seq Scan on join_dim d | — |
JOIN_ORDER(f d) |
Hash Join | Seq Scan on join_dim d | /* matched */ |
JOIN_ORDER(x f d) |
Nested Loop (Disabled: true) |
Index Scan using join_dim_pkey | /* partially matched */ |
문서는 이런 경우 결과 플랜이 "generally worse than if no advice had been specified at all"이라고 쓴다. 에러가 나지 않으므로 쿼리가 돌아간다는 사실만으로는 성공을 판단할 수 없다. 지정한 advice가 해당 쿼리에 적용되었는지, 결과 플랜이 기대한 모양인지를 직접 확인하라는 것이 문서의 권고다.
`pg_plan_advice.feedback_warnings`를 `true`로 두면 지정한 advice가 강제되지 못할 때마다 경고가 발생한다. 기본값은 `false`다. `EXPLAIN` 출력을 매번 읽기 어려운 테스트 세션에서 쓸 만한 설정이다.
나머지 파라미터 하나는 pg_plan_advice.trace_mask(boolean, 기본 false)이며 디버깅 목적의 메시지를 출력한다.
pg_stash_advice로 query ID별 advice 자동 적용
SET pg_plan_advice.advice는 세션 단위 설정이다. 특정 쿼리에 advice를 계속 걸어 두려면 pg_stash_advice 확장 문서가 설명하는 advice stash를 쓴다. stash는 query identifier와 plan advice 문자열의 매핑이다.
준비 조건은 네 가지다.
- SQL 함수를 쓰려면 최소 한 데이터베이스에서
CREATE EXTENSION pg_stash_advice를 실행한다. - advice를 자동 적용할 모든 세션에 모듈이 로드되어 있어야 한다. 문서는
shared_preload_libraries에 추가하고 재시작하는 방식을 보통 최선으로 본다. compute_query_id가 켜져 있어야 한다. 값이auto면 모듈 로드 시 자동으로 켜진다.- stash 생성·수정은 superuser나 해당 함수에 EXECUTE 권한을 받은 사용자만 할 수 있다.
문서가 제공하는 함수 시그니처는 다음과 같다. 실제 호출 예제는 문서에 없다.
pg_create_advice_stash(stash_name text) returns void
pg_drop_advice_stash(stash_name text) returns void
pg_set_stashed_advice(stash_name text, query_id bigint, advice_string text) returns void
pg_get_advice_stashes() returns setof (stash_name text, num_entries bigint)
pg_get_advice_stash_contents(stash_name text) returns setof (stash_name text, query_id bigint, advice_string text)
pg_start_stash_advice_worker() returns void
플래닝 때 어떤 stash를 참조할지는 `pg_stash_advice.stash_name`이 정한다. 기본값은 빈 문자열이고, 이 상태에서는 모듈이 비활성화된다. stash를 만들어 두었는데 advice가 적용되지 않는다면 먼저 이 값을 본다.
성능 주의점과 적용하지 말아야 할 조건
pg_plan_advice 문서는 플래너 판단을 덮어쓰면 쉽게 역효과가 날 수 있다고 경고한다. 데이터 분포가 바뀌었는데 advice가 플랜 조정을 막으면 "a very poor plan may be chosen"이라는 것이다. 문서의 권고는 플래너 선택을 제약하는 위험보다 이점이 클 때만 쓰라는 것이다.
이 경고는 advice 범위를 좁게 잡을 근거가 된다. Generated Plan Advice:의 네 줄을 모두 넣으면 조인 순서, 조인 방식, 스캔 방식, 병렬 여부가 한꺼번에 묶인다. 앞 절의 JOIN_ORDER(f d) 예제처럼 문제가 되는 결정 하나만 고정하면 나머지는 통계에 따라 계속 바뀔 수 있다.
성능 비용은 세 군데서 생긴다.
- 잘못된 advice: 적용 불가능한 advice는 플래닝을 실패시키는 대신 Disabled 플랜을 고르게 만든다. 결과는 대개 advice가 없을 때보다 나쁘다.
- always_store_advice_details:
true면 추가 오버헤드가 생긴다. 문서는 시스템 전체가 아니라 필요한 세션에서만 켜라고 쓴다. - pg_stash_advice 적용 자체: 원문은 "applying plan advice can have a noticeable performance cost even when it does not result in a change to the query plan"이라고 쓴다. 플랜이 그대로여도 비용이 든다는 뜻이므로, stash에는 플래너 오판 위험이 큰 쿼리만 등록하는 편이 맞다.
두 문서 모두 성능 비용을 수치로 제시하지 않는다. 도입 여부는 대상 쿼리에서 advice 유무에 따른 실행 결과를 직접 비교해 판단해야 한다.
pg_stash_advice에는 운영상 제약이 두 가지 더 있다. stash 항목을 바꾸거나 stash_name을 바꿔도 이미 캐시된 플랜에는 영향이 없다. 또 stash는 동적 할당 공유 메모리에 저장되므로 등록 항목이 늘어날수록 메모리 사용량을 살펴야 한다.
stash 생성·수정은 권한이 있는 사용자만 할 수 있지만, `pg_stash_advice.stash_name`은 누구나 자기 세션에서 설정할 수 있다. 문서는 이 때문에 stash 내용이 비권한 사용자에게 노출될 수 있다고 가정하라고 쓴다. advice 문자열에는 다른 사용자가 봐도 되는 내용만 넣고, 노출되면 안 되는 정보를 stash에 담지 않는다.
pg_plan_advice는 생성된 advice를 그대로 고정하는 도구가 아니라, 필요한 결정만 골라 강제하고 피드백으로 검증하는 도구다. 실험 단계에서는 세션 단위 로드와 SET pg_plan_advice.advice로 충분하고, 반복 적용이 필요한 쿼리만 pg_stash_advice로 옮기는 순서가 문서의 경고와 맞는다.
이어서 볼 만한 주제는 PostgreSQL 19 새 기능 전반과 함께 추가된 플래너 훅이다. planner_setup_hook, join_path_setup_hook 같은 훅은 확장 개발 관점에서 이 모듈의 동작 기반을 이해하는 데 이어진다. 기존 pg_hint_plan 대안으로 PostgreSQL 19 쿼리 힌트를 검토하는 경우에는 PostgreSQL 플랜 고정 방식의 운영 차이와 compute_query_id 기반 쿼리 식별 방식이 다음 검토 대상이다.
관련 글
- PostgreSQL 19 새로운 기능 정리: REPACK부터 브레이킹 체인지까지 – PostgreSQL 19는 REPACK 명령어, 병렬 autovacuum, 시퀀스 논리적 복제를 도입했다. 동시에 RADIUS 인증 제거와…
- TypeScript 7 베타 벤치마크 실측 5가지 — CI 환경 성능 병목 완전 분석 – TypeScript 7의 Go 네이티브 컴파일러가 10배 빠르다고 알려졌지만, GitHub Actions CI 환경에서는 28%에 그치는 …