백엔드 데이터 인프라 43편 — postgresql.conf 핵심 설정

이 글은 백엔드 데이터 인프라 시리즈 70편 중 43편이에요. PG 의 모든 설정이 모인 postgresql.conf 의 핵심.

설정 위치·우선순위

1. 명령행 옵션 (가장 강함)
2. ALTER SYSTEM (postgresql.auto.conf)
3. postgresql.conf 메인
4. include 디렉토리
5. 기본값

설정 보기

SHOW shared_buffers;
SHOW ALL;

SELECT name, setting, unit, source
FROM pg_settings
WHERE name LIKE '%memory%';

동적 변경

-- 세션
SET work_mem = '256MB';

-- 전역 (재시작 불필요 항목만)
ALTER SYSTEM SET log_min_duration_statement = 1000;
SELECT pg_reload_conf();

-- 재시작 필요 항목 (shared_buffers 등)
ALTER SYSTEM SET shared_buffers = '4GB';
-- → 서버 재시작 필요

메모리 설정

41편 성능 팁 의 메모리 영역.

shared_buffers = 2GB                  # 호스트 25%
effective_cache_size = 6GB             # 호스트 75%
work_mem = 16MB
maintenance_work_mem = 512MB
huge_pages = try                       # Linux HugePages (운영 권장)

huge_pages

리눅스 huge pages(큰 단위 메모리 페이지) 활용. 대용량 메모리 시스템의 페이지 테이블 부담 감소.

# /etc/sysctl.conf
vm.nr_hugepages = 1024

연결 설정

max_connections = 100                  # 최대 동시 연결
superuser_reserved_connections = 3

max_connections 는 PgBouncer(PG 앞단 연결 풀러) 와의 관계가 중요. PgBouncer pool = 25, max_connections = 100 이면 충분.

listen_addresses = '*'                 # 모든 IP listen
port = 5432

인증 — pg_hba.conf

# TYPE  DATABASE  USER      ADDRESS         METHOD
local   all       postgres                  peer
local   all       all                       scram-sha-256
host    all       all       10.0.0.0/8      scram-sha-256
host    replication replicator 10.0.0.0/8   scram-sha-256
hostssl all       all       0.0.0.0/0       scram-sha-256

scram-sha-256 (해시 기반 인증 알고리즘) = PG 10+ 표준. md5 는 deprecated.

-- 변경 후 reload
SELECT pg_reload_conf();

로깅

log_destination = 'stderr'
logging_collector = on
log_directory = 'log'
log_filename = 'postgresql-%Y-%m-%d.log'
log_rotation_age = 1d
log_rotation_size = 100MB
log_truncate_on_rotation = on

log_min_messages = warning             # 로그 수준
log_min_error_statement = error
log_min_duration_statement = 1000      # 1초+ 쿼리 로그
log_checkpoints = on
log_connections = on
log_disconnections = on
log_duration = off                     # 모든 쿼리 시간 (디버깅 시만)
log_lock_waits = on
log_temp_files = 0                     # 모든 임시 파일 (work_mem 부족)
log_autovacuum_min_duration = 0       # 모든 autovacuum
log_line_prefix = '%t [%p]: [%l-1] user=%u,db=%d,client=%h '

로그 분석 도구

pgBadger -o report.html /var/log/postgresql/*.log

pgBadger(PG 로그 파싱 리포터) 는 PG 운영의 표준 분석 도구. 슬로우 쿼리·연결·임시 파일·체크포인트 모두 시각화.

체크포인트·WAL

wal_level = replica                    # 복제 가능 수준
max_wal_size = 4GB
min_wal_size = 1GB
checkpoint_timeout = 15min
checkpoint_completion_target = 0.9
wal_buffers = 16MB
wal_compression = on                   # PG 14+
synchronous_commit = on                # 안전성 ↑
fsync = on                              # 안전성 ↑↑

WAL(Write-Ahead Log, 트랜잭션 선행 로그) 은 복제와 크래시 복구의 토대. fsync = on 은 절대 변경 X — 끄면 크래시 시 데이터 손실.

복제

# Primary
wal_level = replica
max_wal_senders = 10
wal_keep_size = 16GB
hot_standby = on

# Replica
primary_conninfo = 'host=primary.example.com user=replicator'

물리 복제 표준. 논리 복제 (wal_level = logical) 는 부분 복제·다른 PG 버전 간.

autovacuum

autovacuum = on
autovacuum_max_workers = 4
autovacuum_naptime = 1min
autovacuum_vacuum_threshold = 50
autovacuum_vacuum_scale_factor = 0.2   # 큰 테이블엔 너무 큼
autovacuum_analyze_threshold = 50
autovacuum_analyze_scale_factor = 0.1
autovacuum_freeze_max_age = 200000000  # Wraparound 방지
autovacuum_vacuum_cost_delay = 2ms     # CPU 부담 줄임

큰 테이블 = ALTER TABLE SET (autovacuum_vacuum_scale_factor = 0.05).

계획자

random_page_cost = 1.1                # SSD 시 (HDD 는 4)
effective_io_concurrency = 200         # SSD 시 (HDD 는 1)
default_statistics_target = 100       # 통계 정밀도

SSD = random_page_cost 낮추기 무조건. 기본 4 는 HDD 가정. PG 가 인덱스를 더 적극 사용.

확장·로컬

shared_preload_libraries = 'pg_stat_statements,auto_explain'
timezone = 'Asia/Seoul'
lc_messages = 'en_US.UTF-8'
default_text_search_config = 'pg_catalog.simple'

pg_stat_statements (쿼리 통계 누적 확장) = 운영 필수. auto_explain (느린 쿼리 EXPLAIN 자동 로깅 확장) 은 디버깅에 큰 도움.

운영 표준 한 묶음

# 호스트 8GB·SSD 가정
shared_buffers = 2GB
effective_cache_size = 6GB
work_mem = 16MB
maintenance_work_mem = 512MB
max_connections = 100

wal_level = replica
max_wal_size = 4GB
checkpoint_timeout = 15min
checkpoint_completion_target = 0.9
wal_compression = on
synchronous_commit = on

random_page_cost = 1.1
effective_io_concurrency = 200

log_min_duration_statement = 1000
log_checkpoints = on
log_lock_waits = on
log_temp_files = 0
log_autovacuum_min_duration = 0

shared_preload_libraries = 'pg_stat_statements,auto_explain'
auto_explain.log_min_duration = '5s'
auto_explain.log_analyze = on
auto_explain.log_buffers = on

autovacuum_max_workers = 4
autovacuum_vacuum_cost_delay = 2ms

이 한 묶음이 — 8GB·SSD 호스트의 합리적 시작점. 운영에서 모니터링 후 조정.

RDS 의 경우

RDS = postgresql.conf 직접 X. 파라미터 그룹 으로:

AWS Console → RDS → Parameter Groups → 새 그룹 → 수정

또는 IaC(Infrastructure as Code, 인프라 코드화):

resource "aws_db_parameter_group" "main" {
  name   = "pg18-prod"
  family = "postgres18"

  parameter { name = "shared_buffers" value = "{DBInstanceClassMemory/4}" }
  parameter { name = "log_min_duration_statement" value = "1000" }
}

함정 5가지

(1) 기본값 그대로

PG 기본 = 1GB 호스트 가정. 운영 = 무조건 튜닝.

(2) random_page_cost = 4 (HDD 기본)

SSD = 1.1. PG 계획자가 인덱스 사용 결정에 영향.

(3) pg_stat_statements 안 박음

운영 환경에 모니터링이 없으면 느린 쿼리를 발견 못 함.

(4) auto_explain 안 활용

슬로우 쿼리의 EXPLAIN 을 자동 로깅. 디버깅 매우 편함.

(5) ALTER SYSTEM vs 파일 수정 혼동

ALTER SYSTEM 은 postgresql.auto.conf 에 박힌다 (postgresql.conf 와 별도). 두 파일 충돌 시 auto.conf 가 우세. 운영은 한 가지 방식으로 통일.

한 줄 정리 — postgresql.conf 핵심 영역 = 메모리·연결·로그·체크포인트·복제·autovacuum·계획자·확장. SSD = random_page_cost 1.1. pg_stat_statements + auto_explain 필수. RDS = 파라미터 그룹.

시험 직전 한 번 더 — postgresql.conf 입문자가 매번 헷갈리는 것

• 우선순위 = 명령행 > ALTER SYSTEM > 파일 > 기본
• SHOW name·SHOW ALL
• pg_settings 시스템 뷰
• ALTER SYSTEM = 동적 (postgresql.auto.conf)
• pg_reload_conf() = reload (재시작 불필요 항목)
• shared_buffers = 25%
• effective_cache_size = 75%
• work_mem = 16MB (동적 SET)
• huge_pages = try (Linux)
• max_connections = 100 (PgBouncer 와 짝)
• listen_addresses = '*'
• pg_hba.conf = 인증 (scram-sha-256)
• logging_collector = on
• log_min_duration_statement = 1000 (1초+)
• log_checkpoints·log_lock_waits·log_temp_files
• pgBadger = 로그 분석
• wal_level = replica
• checkpoint_timeout 15min
• wal_compression on (PG 14+)
• fsync = on (절대 변경 X)
• synchronous_commit = on
• random_page_cost = 1.1 (SSD)
• effective_io_concurrency = 200 (SSD)
• autovacuum_vacuum_scale_factor = 0.05~0.1 (큰 테이블)
• shared_preload_libraries = 'pg_stat_statements,auto_explain'
• auto_explain.log_min_duration = 5s
• RDS = 파라미터 그룹
• 운영 첫 셋업 = 10개 설정 체크
• timezone = 'Asia/Seoul'

시리즈 다른 편 (앞뒤 글 모음)

이전 글:

• 38편 — MVCC 격리 수준과 동시성 함정
• 39편 — 전문 검색 to_tsvector to_tsquery
• 40편 — EXPLAIN 쿼리 계획 읽기
• 41편 — 성능 팁 종합
• 42편 — 운영 설치 바이너리·Docker·관리 서비스

다음 글:

• 44편 — 사용자·역할 관리 CREATE ROLE GRANT
• 45편 — 데이터베이스 관리 생성·복제·드롭
• 46편 — 백업과 복구 pg_dump·PITR
• 47편 — Redis란 + PostgreSQL과의 역할 분담
• 48편 — Redis 데이터 타입 13종 한 번에 정리