PostgreSQL 18.3 서버 환경 설정 매개 변수 21개 정리: 기본값과 운영 적용 방법

PostgreSQL 18에서는 비동기 I/O, 자동 VACUUM, 쿼리 최적화, 복제 슬롯 관리 및 인증 설정과 관련된 서버 환경 설정 매개 변수가 추가되었습니다. 이 글에서는 PostgreSQL 18.3 환경에서 확인할 주요 매개 변수 21개를 기본값, 변경 적용 방식, 운영 관점으로 정리합니다.

버전 범위: 아래 항목은 주로 PostgreSQL 18 메이저 버전에서 도입된 기능입니다. 모두 PostgreSQL 18.3에서 처음 추가된 설정이라는 의미는 아닙니다. 또한 특정 서버에서 조회한 값은 공식 기본값과 다를 수 있습니다.

1. 기본값과 현재 설정값을 구분하기

pg_settings에서 setting은 현재 세션에 적용된 값, boot_val은 설정을 별도로 지정하지 않았을 때의 기본값입니다. reset_val은 해당 세션에서 RESET 명령을 실행했을 때 돌아갈 값입니다. 숫자만 확인하면 단위를 놓칠 수 있으므로 unit도 함께 조회해야 합니다.

SQL — 서버 버전과 설정값 조회:

SELECT version();

SELECT name,
       setting AS current_value,
       unit,
       boot_val AS boot_default,
       reset_val,
       context,
       source,
       pending_restart
FROM pg_settings
WHERE name IN (
    'autovacuum_vacuum_max_threshold',
    'autovacuum_worker_slots',
    'enable_distinct_reordering',
    'enable_self_join_elimination',
    'extension_control_path',
    'file_copy_method',
    'idle_replication_slot_timeout',
    'io_max_combine_limit',
    'io_max_concurrency',
    'io_method',
    'io_workers',
    'log_lock_failures',
    'max_active_replication_origins',
    'md5_password_warnings',
    'num_os_semaphores',
    'oauth_validator_libraries',
    'ssl_groups',
    'ssl_tls13_ciphers',
    'track_cost_delay_timing',
    'vacuum_max_eager_freeze_failure_rate',
    'vacuum_truncate'
)
ORDER BY name;

제공된 표에서 수정할 부분

• idle_replication_slot_timeout의 공식 기본값은 0입니다. 조회값이 301이라면 301초로 설정된 환경인지 source를 확인합니다.
• track_cost_delay_timing의 공식 기본값은 off입니다.
• io_max_combine_limit의 기본값은 128kB입니다. 일반적인 8KB 블록 환경에서는 pg_settings에 값 16, 단위 8kB로 표시됩니다.
• io_max_concurrency는 기본 설정 -1에서 서버 자원에 따라 자동 산정됩니다. 조회된 64는 자동 계산 결과일 수 있습니다.
• num_os_semaphores의 174는 모든 서버에 공통으로 적용되는 고정 기본값이 아닙니다.

2. context별 설정 적용 방식

context는 설정을 언제, 어떤 권한으로 변경할 수 있는지를 나타냅니다. 특히 postmaster 설정은 재시작이 필요하므로 reload만 실행해서는 변경되지 않습니다.

주요 context의 의미

context	의미	적용 방법
postmaster	서버 시작 시 결정하는 설정	설정 변경 후 PostgreSQL 재시작
sighup	서버 설정 파일을 다시 읽어 반영하는 설정	설정 변경 후 reload
user	일반 사용자가 세션에서 변경할 수 있는 설정	SET 또는 역할·데이터베이스별 설정
superuser	슈퍼유저 또는 해당 매개 변수의 SET 권한을 받은 사용자가 변경	권한을 가진 세션에서 SET 등으로 변경
internal	서버가 계산하거나 보고하는 읽기 전용 값	직접 변경 불가

3. 주요 서버 환경 설정 매개 변수 21개

아래 표는 PostgreSQL 18 계열의 기본 동작을 기준으로 정리했습니다. 운영 서버에서는 패키지 구성, 초기화 과정, 설정 파일 및 서버 자원에 따라 실제 값이 달라질 수 있습니다.

매개 변수별 기본값과 주요 기능

매개 변수	기본값·기본 동작	context	설명
autovacuum_vacuum_max_threshold	100000000	sighup	UPDATE·DELETE 기반 자동 VACUUM 실행 임계값의 상한
autovacuum_worker_slots	통상 16	postmaster	autovacuum 작업자용으로 예약하는 백엔드 슬롯 수
enable_distinct_reordering	on	user	DISTINCT 키의 내부 처리 순서를 조정해 정렬 비용을 줄이는 최적화
enable_self_join_elimination	on	user	유일성 등을 근거로 불필요한 self-join을 제거하는 최적화
extension_control_path	$system	superuser	확장 모듈의 control 파일을 검색할 경로
file_copy_method	copy	user	데이터베이스 파일 복사 시 copy 또는 지원되는 clone 방식 선택
idle_replication_slot_timeout	0초	sighup	장기간 사용하지 않은 복제 슬롯의 무효화 시간. 0은 비활성화
io_max_combine_limit	128kB	postmaster	결합 I/O 크기의 서버 전역 상한. io_combine_limit을 제한
io_max_concurrency	-1: 자동 산정, 최대 64	postmaster	한 프로세스가 동시에 실행할 수 있는 I/O 작업 수의 상한
io_method	worker	postmaster	I/O 실행 방식 선택: worker, io_uring, sync
io_workers	3	sighup	io_method가 worker일 때 사용하는 I/O 작업자 프로세스 수
log_lock_failures	off	superuser	잠금 획득 실패 상세 기록. PostgreSQL 18에서는 SELECT NOWAIT 실패 지원
max_active_replication_origins	10	postmaster	동시에 추적할 수 있는 활성 복제 오리진 수
md5_password_warnings	on	user	MD5 비밀번호 사용 관련 지원 중단 경고 표시
num_os_semaphores	환경에 따라 계산	internal	서버가 필요로 하는 OS 세마포어 수 보고
oauth_validator_libraries	빈 문자열	sighup	OAuth bearer 토큰 검증에 사용할 라이브러리 목록
ssl_groups	X25519:prime256v1	sighup	TLS 키 교환에 사용할 그룹 목록
ssl_tls13_ciphers	빈 문자열	sighup	TLS 1.3 암호 스위트 목록. 빈 값은 OpenSSL 기본 목록 사용
track_cost_delay_timing	off	superuser	비용 기반 VACUUM·ANALYZE 지연 시간 측정
vacuum_max_eager_freeze_failure_rate	0.03	user	eager scanning 중 all-frozen 처리에 실패한 페이지의 허용 비율
vacuum_truncate	on	user	VACUUM이 테이블 파일 끝의 빈 페이지를 반환하도록 허용

4. 자동 VACUUM과 Freeze 설정 이해하기

autovacuum_vacuum_max_threshold

기존 자동 VACUUM 임계값은 테이블 크기에 비례해 증가합니다. 대형 테이블에서는 실행 시점까지 많은 dead tuple이 누적될 수 있으므로, PostgreSQL 18에서는 이 임계값에 상한을 둘 수 있습니다.

UPDATE·DELETE 기반 실행 조건의 임계값은 다음과 같이 계산합니다.

실행 임계값 =
min(
    autovacuum_vacuum_threshold
    + autovacuum_vacuum_scale_factor × 추정 튜플 수,
    autovacuum_vacuum_max_threshold
)

기본 상한은 1억 개입니다. -1로 설정하면 상한을 사용하지 않습니다. 이 값은 dead tuple의 실제 누적량을 항상 상한 아래로 유지하는 보장이 아닙니다. 작업자 부족이나 장기 트랜잭션이 있으면 VACUUM 실행·정리가 지연될 수 있습니다.

autovacuum_worker_slots

autovacuum_worker_slots는 작업자용 슬롯을 예약하고, autovacuum_max_workers는 실제 동시 실행 작업자 수를 제한합니다. 슬롯이 16개라고 해서 작업자 16개가 항상 실행되는 것은 아닙니다. 예약한 슬롯 범위에서는 autovacuum_max_workers를 reload로 조정할 수 있습니다.

vacuum_max_eager_freeze_failure_rate

PostgreSQL 18은 일반 VACUUM에서도 일부 all-visible 페이지를 추가 검사해 미리 freeze할 수 있습니다. 이를 eager scanning이라고 합니다. 이 설정은 추가 검사 후 페이지를 all-frozen 상태로 만들지 못한 경우의 허용 한도를 테이블 전체 페이지 수에 대한 비율로 정합니다.

기본값 0.03은 실패 페이지 한도를 3%로 둔다는 의미이며, 전체 페이지의 3%만 검사한다는 뜻은 아닙니다. 0은 eager scanning을 비활성화합니다. 필수적인 트랜잭션 ID wraparound 방지 freeze 기능까지 끄는 설정은 아닙니다.

vacuum_truncate

일반 VACUUM은 테이블 내부의 빈 공간을 재사용 가능하게 정리하지만, 테이블 파일 끝에 빈 페이지가 있으면 이를 잘라 OS에 반환할 수도 있습니다. vacuum_truncate는 이 동작을 제어합니다. 파일 끝을 줄이는 과정에는 ACCESS EXCLUSIVE 잠금이 필요하므로, 잠금 영향이 민감한 테이블에서는 적용 여부를 검토합니다.

5. 비동기 I/O 설정 이해하기

io_method는 I/O 실행 방식을, io_workers는 worker 방식의 작업자 수를 결정합니다. io_max_concurrency는 프로세스별 동시 작업 수를 제한하고, io_max_combine_limit는 결합 I/O의 최대 크기를 제한합니다. 각각 다른 대상을 제어하므로 같은 의미의 설정으로 취급하면 안 됩니다.

• worker: 별도 I/O 작업자 프로세스를 사용하는 기본 방식
• io_uring: 지원되는 빌드·OS 환경에서 io_uring 사용
• sync: 비동기 처리 대상 I/O를 동기 방식으로 실행

I/O 동시성을 높이면 일부 작업에서 대기 시간을 줄일 수 있지만, 공유 스토리지에서는 다른 세션의 지연이 늘어날 수 있습니다. 기존 effective_io_concurrency 및 maintenance_io_concurrency와 함께 확인하고, 실제 부하에서 처리량과 지연 시간을 비교합니다.

SQL — 관련 설정 확인:

SHOW io_method;
SHOW io_workers;
SHOW io_max_concurrency;
SHOW io_max_combine_limit;
SHOW io_combine_limit;
SHOW effective_io_concurrency;
SHOW maintenance_io_concurrency;

6. 쿼리 최적화와 파일·확장 모듈 설정

DISTINCT 재정렬과 self-join 제거

enable_distinct_reordering은 DISTINCT 키의 내부 처리 순서를 기존 정렬 순서 등에 맞춰 최적화합니다. enable_self_join_elimination은 결과가 동일함을 증명할 수 있는 불필요한 self-join을 제거합니다. self-join SQL의 사용을 금지하는 설정은 아닙니다.

두 설정은 기본적으로 켜져 있습니다. 특정 쿼리의 실행 계획을 비교할 때는 세션 또는 트랜잭션 범위에서 임시로 변경해 확인할 수 있습니다. 실행 계획만 살펴보려면 쿼리를 실제 실행하는 EXPLAIN ANALYZE 대신 EXPLAIN을 사용합니다.

SQL — 현재 세션 설정 확인:

SHOW enable_distinct_reordering;
SHOW enable_self_join_elimination;

file_copy_method

이 설정은 CREATE DATABASE ... STRATEGY=FILE_COPY와 ALTER DATABASE ... SET TABLESPACE의 파일 복사에 영향을 줍니다. clone은 OS와 파일시스템이 지원하는 복사 최적화를 활용할 수 있지만, 모든 환경에서 블록 공유나 성능 향상을 보장하지는 않습니다. SQL COPY 데이터 가져오기·내보내기 방식을 지정하는 설정은 아닙니다.

extension_control_path

기본값 $system은 PostgreSQL에 내장된 확장 모듈 검색 경로를 의미합니다. 지정한 각 경로 아래에는 extension 하위 디렉터리가 있어야 합니다. control·SQL 파일 경로와 공유 라이브러리 경로는 구분되므로, 비표준 위치에 확장 모듈을 설치하면 dynamic_library_path도 함께 확인합니다. 검색 경로를 추가하는 것만으로 확장 모듈이 설치되지는 않습니다.

7. 복제·로그·인증 설정의 운영 포인트

idle_replication_slot_timeout

복제 지연량이 아니라 슬롯이 사용되지 않은 시간을 기준으로 합니다. 설정 시간을 초과한 비활성 슬롯은 체크포인트 시점에 무효화되므로, 시간이 지나자마자 즉시 무효화되는 것은 아닙니다. 기본값 0에서는 시간 기반 무효화가 비활성화됩니다.

장기 중단된 복제 소비자의 슬롯이 무효화되면 기존 위치에서 복제를 재개하지 못할 수 있습니다. 백업·점검·장애 복구에 필요한 시간을 고려해 값을 결정하고, WAL 보관량 제한인 max_slot_wal_keep_size와 구분해 관리합니다.

max_active_replication_origins

논리 복제 적용 위치를 추적하는 복제 오리진의 동시 사용 한도입니다. 논리 복제 구독 수뿐 아니라 초기 테이블 동기화에 필요한 여유도 고려합니다. max_replication_slots는 복제 슬롯 수를, 이 설정은 활성 오리진 수를 제어합니다.

log_lock_failures와 track_cost_delay_timing

log_lock_failures는 PostgreSQL 18에서 SELECT NOWAIT 잠금 획득 실패의 상세 분석에 사용합니다. 오래 기다린 잠금을 기록하는 log_lock_waits와 역할이 다릅니다. track_cost_delay_timing은 VACUUM·ANALYZE의 비용 기반 지연 시간을 측정하며, 시간 측정에 따른 부하를 고려해 사용합니다.

MD5 경고와 OAuth 검증 라이브러리

md5_password_warnings를 끄면 경고가 숨겨질 뿐, 비밀번호 저장 방식이나 인증 방식이 변경되지는 않습니다. SCRAM 전환은 클라이언트 지원 여부, 비밀번호 재설정 및 pg_hba.conf 인증 규칙을 함께 검토해야 합니다.

oauth_validator_libraries는 OAuth 토큰 검증 라이브러리 목록입니다. 이 값만 지정한다고 OAuth 인증이 완성되는 것은 아닙니다. 검증 라이브러리 설치와 인증 규칙 구성이 함께 필요합니다.

ssl_groups와 ssl_tls13_ciphers

ssl_groups는 TLS 키 교환 그룹을 지정하며, 이전 ssl_ecdh_curve 설정을 확장한 항목입니다. ssl_tls13_ciphers는 TLS 1.3 암호 스위트를 별도로 지정합니다. 빈 문자열이면 OpenSSL 기본 목록을 사용하며, TLS 암호화가 꺼지는 것은 아닙니다. 두 설정의 변경 시에는 기존 JDBC·libpq 클라이언트와의 연결 호환성을 확인합니다.

8. 설정 변경 후 확인 방법

설정을 변경하기 전에 적용 중인 파일과 값을 확인합니다. 다음 조회는 설정 변경 없이 실행할 수 있습니다.

SQL — 설정 파일 위치와 파싱 오류 확인:

SHOW config_file;
SHOW hba_file;

SELECT sourcefile,
       sourceline,
       name,
       setting,
       applied,
       error
FROM pg_file_settings
WHERE error IS NOT NULL;

pg_file_settings 조회에는 적절한 관리 권한이 필요합니다. 오류가 없다는 것만으로 모든 값이 현재 서버에 적용되었다고 판단하지 않습니다.

sighup 설정을 변경한 뒤에는 권한을 가진 계정으로 reload합니다. postmaster 설정은 해당 인스턴스를 재시작해야 합니다.

SQL — reload 및 재시작 대기 설정 확인:

SELECT pg_reload_conf();

SELECT name,
       setting,
       unit,
       context,
       pending_restart
FROM pg_settings
WHERE pending_restart
ORDER BY name;

pg_reload_conf()의 반환값이 true여도 모든 설정 변경이 성공적으로 적용되었다는 의미는 아닙니다. 서버 로그, 실제 설정값 및 pending_restart를 함께 확인합니다. 하나의 서버에서 여러 PostgreSQL 인스턴스를 운영한다면 접속 포트와 설정 파일 경로를 확인해 대상 인스턴스를 구분합니다.

9. 공식 참고 문서

• PostgreSQL 18.0 릴리스 노트
• PostgreSQL 18.3 릴리스 노트
• 리소스 사용량 및 I/O 설정
• 자동 VACUUM 및 Freeze 설정
• 쿼리 계획 설정
• 복제 관련 설정
• 클라이언트 기본값 및 확장 모듈 경로
• 연결·인증·TLS 설정
• 오류 보고 및 로그 설정
• 실행 시간 통계 설정
• 읽기 전용 서버 정보