PostgreSQL 55P02 오류 원인과 해결 방법 완벽 가이드

55P02
2026년 09월 21일 | DBMS Error 가이드

이 글에서 다루는 내용

55P02 에러의 원인 분석, 해결 SQL, 예방 방법을 실무 관점에서 정리합니다.

55P02 cant change runtime param 는?

PostgreSQL 에러 코드 55P02 (cant\_change\_runtime\_param)는 이미 데이터베이스 서버가 시작된 이후에는 변경할 수 없는 파라미터를 런타임 중에 수정하려고 시도할 때 발생합니다. 일부 설정 파라미터는 서버 기동 시(startup)에만 적용되며, SET 명령이나 ALTER SYSTEM 이후 SELECT pg_reload_conf() 방식으로는 반영이 불가능합니다. 주로 postgresql.conf의 특정 파라미터를 동적으로 바꾸려 할 때 DBA들이 처음 마주치는 에러입니다.

주요 발생 원인

1. 서버 재시작이 필요한 파라미터를 SET으로 변경 시도

PostgreSQL의 파라미터는 변경 가능 컨텍스트(context)에 따라 internal, postmaster, sighup, superuser, user 등으로 분류됩니다. postmaster 컨텍스트에 속하는 파라미터(예: max_connections, shared_buffers, wal_level 등)는 서버를 완전히 재시작해야만 적용됩니다. 세션 또는 트랜잭션 레벨에서 SET 명령으로 이러한 파라미터를 변경하려 하면 55P02 에러가 즉시 발생합니다.

2. ALTER SYSTEM 이후 pg_reload_conf()만으로 처리하려는 시도

ALTER SYSTEM SET shared_buffers = '2GB'처럼 postgresql.auto.conf에 값을 기록한 뒤, 서버 재시작 없이 SELECT pg_reload_conf()만 실행하면 해당 파라미터가 적용되지 않고 에러가 발생합니다. pg_reload_conf()는 sighup 컨텍스트 파라미터만 반영할 수 있기 때문에, 재시작이 필요한 파라미터에 이 방식을 사용하는 것은 잘못된 접근입니다. 실무에서 신규 서버 세팅이나 튜닝 작업 중 빈번히 발생하는 실수입니다.

3. 애플리케이션 코드에서 커넥션 풀링 환경의 SET 명령 오용

PgBouncer 등의 커넥션 풀러를 사용하는 환경에서, 애플리케이션이 커넥션을 획득하자마자 SET 명령으로 런타임 파라미터를 변경하려는 코드가 잘못된 파라미터를 대상으로 실행될 경우 이 에러가 발생합니다. 특히 ORM 레이어나 프레임워크가 자동으로 세션 파라미터를 설정하는 과정에서 postmaster 컨텍스트 파라미터를 건드리면 문제가 생깁니다. 이 경우 에러 로그를 보기 전까지 원인 파악이 어려운 경우가 많습니다.

해결 방법

원인 1 해결: 파라미터 컨텍스트 확인 후 재시작

먼저 변경하려는 파라미터의 컨텍스트를 확인합니다.

-- 파라미터의 컨텍스트 확인
SELECT name, setting, context, short_desc
FROM pg_settings
WHERE name IN ('max_connections', 'shared_buffers', 'wal_level', 'listen_addresses');

context 컬럼이 postmaster인 경우 반드시 서버를 재시작해야 합니다.

-- ALTER SYSTEM으로 설정 변경 (postgresql.auto.conf에 저장됨)
ALTER SYSTEM SET max_connections = 300;
ALTER SYSTEM SET shared_buffers = '4GB';

-- 변경사항 확인 (실제 반영은 재시작 후)
SELECT name, setting, pending_restart
FROM pg_settings
WHERE pending_restart = true;

위 쿼리에서 pending_restart = true로 표시된 항목은 서버 재시작 전까지 반영되지 않습니다. 이후 OS 레벨에서 재시작을 수행합니다.

# systemd 환경에서 PostgreSQL 재시작
sudo systemctl restart postgresql-16

# 또는 pg_ctl 사용
pg_ctl restart -D /var/lib/pgsql/16/data

원인 2 해결: sighup 파라미터와 postmaster 파라미터 구분

sighup 컨텍스트 파라미터는 재시작 없이 pg_reload_conf()로 반영 가능합니다.

-- sighup 컨텍스트 파라미터 목록 조회
SELECT name, setting, context
FROM pg_settings
WHERE context = 'sighup'
ORDER BY name;

-- sighup 파라미터는 이렇게 변경 가능
ALTER SYSTEM SET log_min_duration_statement = 1000;
ALTER SYSTEM SET work_mem = '64MB';

-- 재로드로 즉시 반영 (재시작 불필요)
SELECT pg_reload_conf();

-- 반영 여부 확인
SHOW work_mem;
SHOW log_min_duration_statement;

원인 3 해결: 애플리케이션 레벨 SET 명령 점검

애플리케이션에서 세션 파라미터를 설정할 때는 반드시 user 또는 superuser 컨텍스트 파라미터만 대상으로 해야 합니다.

-- 올바른 사용: user 컨텍스트 파라미터 세션 설정
SET search_path TO myschema, public;
SET work_mem = '32MB';
SET statement_timeout = '30s';
SET timezone = 'Asia/Seoul';

-- 잘못된 사용 예 (에러 발생)
-- SET max_connections = 200;  -- postmaster 컨텍스트, 불가
-- SET shared_buffers = '1GB'; -- postmaster 컨텍스트, 불가

-- 데이터베이스 또는 롤 단위로 파라미터 기본값 설정
ALTER DATABASE mydb SET work_mem = '64MB';
ALTER ROLE myapp_user SET search_path TO myschema, public;
ALTER ROLE myapp_user SET statement_timeout = '60s';

에러 발생 시 로그에서 정확한 파라미터를 확인하고 컨텍스트를 재검증하는 루틴을 만들어두는 것이 좋습니다.

-- 에러 발생 후 빠른 진단 쿼리
SELECT
    name,
    setting,
    unit,
    context,
    vartype,
    min_val,
    max_val,
    pending_restart
FROM pg_settings
WHERE name = '문제가_된_파라미터명';

예방 방법

1. 파라미터 변경 전 컨텍스트를 반드시 확인하는 표준 절차 수립

모든 파라미터 변경 작업 전에 pg_settings 뷰를 조회하여 context 값을 먼저 확인하는 것을 팀 내 표준 절차로 정착시켜야 합니다. postmaster 컨텍스트 파라미터는 변경 계획서에 서버 재시작 일정을 명시하고, 서비스 다운타임을 최소화하기 위해 유지보수 윈도우를 확보한 뒤 진행하는 것이 안전합니다. CI/CD 파이프라인에 파라미터 컨텍스트 사전 검증 스크립트를 포함시키면 운영 환경에서의 실수를 사전에 막을 수 있습니다.

-- 팀 공용 파라미터 컨텍스트 점검 쿼리 (변경 작업 전 필수 실행)
SELECT
    name,
    setting AS current_value,
    context,
    CASE context
        WHEN 'postmaster' THEN '⛔ 서버 재시작 필요'
        WHEN 'sighup'     THEN '✅ pg_reload_conf() 가능'
        WHEN 'superuser'  THEN '✅ 슈퍼유저 SET 가능'
        WHEN 'user'       THEN '✅ 일반 SET 가능'
        ELSE context
    END AS action_required
FROM pg_settings
WHERE name = ANY(ARRAY['max_connections','shared_buffers','work_mem','wal_level']);

2. pending\_restart 모니터링 알림 설정

ALTER SYSTEM으로 파라미터를 변경했지만 서버 재시작이 이루어지지 않은 상태를 감지하는 모니터링을 설정해두면, 설정이 반영되지 않은 채 운영되는 리스크를 줄일 수 있습니다. Prometheus + pg_exporter 또는 Zabbix 등의 모니터링 도구에 아래 쿼리를 기반으로 한 알림 규칙을 추가해 두는 것을 권장합니다.

-- pending_restart 파라미터 존재 시 알림 트리거용 쿼리
SELECT COUNT(*) AS pending_restart_count
FROM pg_settings
WHERE pending_restart = true;

-- 상세 목록 확인
SELECT name, setting, context
FROM pg_settings
WHERE pending_restart = true;