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

55P02
2026년 07월 18일 | DBMS Error 가이드

이 글에서 다루는 내용

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

55P02 cant change runtime param 는?

PostgreSQL 에러 코드 55P02 (cant\_change\_runtime\_param)은 실행 중인 세션에서 이미 고정된 파라미터를 동적으로 변경하려 할 때 발생합니다. 일부 설정값은 PostgreSQL 서버 시작 시점 또는 특정 컨텍스트에서만 변경이 허용되며, 런타임 중에는 수정이 불가능합니다. 예를 들어 max_connections, shared_buffers와 같이 서버 재시작이 필요한 파라미터를 SET 명령으로 변경하려 할 때 이 에러가 발생합니다.

주요 발생 원인

1. 서버 재시작이 필요한 파라미터를 런타임에 변경 시도

max_connections, shared_buffers, wal_level 등 PostgreSQL 내부적으로 context = postmaster로 분류된 파라미터들은 서버가 시작될 때만 읽히고 적용됩니다. 운영 중에 SET 명령이나 ALTER SYSTEM SET으로 즉시 반영되기를 기대하며 변경을 시도하면 55P02 에러가 발생합니다. 이러한 파라미터들은 pg_settings 뷰의 context 컬럼에서 postmaster로 명시되어 있으므로 변경 전 반드시 확인해야 합니다.

2. 트랜잭션 블록 내부에서 허용되지 않는 파라미터 변경 시도

일부 파라미터는 트랜잭션 블록(BEGIN ... COMMIT) 내부에서는 변경할 수 없으며, 트랜잭션 외부에서만 설정 가능합니다. 예를 들어 transaction_isolation 수준을 트랜잭션이 이미 시작된 후에 변경하려는 경우가 대표적입니다. 이 경우 PostgreSQL은 해당 파라미터의 변경 컨텍스트를 위반한 것으로 판단하고 55P02 에러를 반환합니다.

3. 읽기 전용 트랜잭션 또는 슬레이브(Standby) 서버에서 파라미터 변경 시도

Hot Standby 서버(읽기 전용 복제본)에서 특정 파라미터를 SET 명령으로 변경하려 할 때도 이 에러가 발생할 수 있습니다. 스탠바이 서버는 쓰기 작업 자체가 제한되며, 일부 설정 변경도 마찬가지로 금지됩니다. 애플리케이션이 Primary/Standby를 구분하지 않고 동일한 파라미터 변경 쿼리를 실행할 때 운영 환경에서 자주 발생하는 실수입니다.

해결 방법

원인 1: 서버 재시작이 필요한 파라미터 변경

먼저 변경하려는 파라미터의 context를 확인하세요.

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

context가 postmaster인 경우 ALTER SYSTEM으로 설정 후 서버를 재시작해야 합니다.

-- postgresql.conf에 영구 반영 (재시작 필요)
ALTER SYSTEM SET max_connections = 300;
ALTER SYSTEM SET shared_buffers = '2GB';

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

# 서버 재시작 (systemd 기준)
sudo systemctl restart postgresql

context가 sighup인 경우에는 재시작 없이 reload로 반영 가능합니다.

-- reload로 반영 가능한 파라미터 변경
ALTER SYSTEM SET log_min_duration_statement = '1000';
SELECT pg_reload_conf();

-- 적용 확인
SHOW log_min_duration_statement;

원인 2: 트랜잭션 블록 내 파라미터 변경

트랜잭션 시작 전에 파라미터를 설정하거나, SET LOCAL을 올바르게 활용해야 합니다.

-- 잘못된 예시: 트랜잭션 시작 후 isolation level 변경 시도 → 에러 발생
BEGIN;
SET TRANSACTION ISOLATION LEVEL SERIALIZABLE; -- 이미 트랜잭션이 시작된 경우 에러

-- 올바른 예시: 트랜잭션 시작과 동시에 격리 수준 설정
BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE;
SELECT * FROM orders WHERE status = 'pending';
COMMIT;

-- SET LOCAL: 트랜잭션 블록 내에서만 유효한 파라미터 설정 (트랜잭션 종료 시 원복)
BEGIN;
SET LOCAL work_mem = '256MB';
SELECT * FROM large_table ORDER BY complex_column;
COMMIT;
-- 트랜잭션 종료 후 work_mem은 원래 값으로 복원됨

원인 3: Standby 서버에서의 파라미터 변경

애플리케이션 코드에서 접속 대상 서버를 판별한 후 파라미터 변경을 수행해야 합니다.

-- 현재 서버가 Primary인지 Standby인지 확인
SELECT pg_is_in_recovery();
-- 결과가 false이면 Primary, true이면 Standby

-- Standby에서 허용되는 읽기 전용 파라미터 확인
SELECT name, setting, context
FROM pg_settings
WHERE context = 'user'
ORDER BY name;

-- 애플리케이션에서 조건부 실행 예시 (PL/pgSQL)
DO $$
BEGIN
    IF NOT pg_is_in_recovery() THEN
        PERFORM set_config('work_mem', '128MB', false);
    END IF;
END;
$$;

예방 방법

1. 파라미터 변경 전 pg\_settings 뷰로 context 반드시 확인

운영 환경에서 파라미터를 변경하기 전에 항상 pg_settings의 context 컬럼을 조회하는 습관을 들이세요. postmaster, sighup, superuser, user 등의 컨텍스트에 따라 변경 방법이 달라지며, 이를 사전에 파악하면 55P02 에러를 원천적으로 방지할 수 있습니다.

-- 변경 예정 파라미터 사전 검증 쿼리
SELECT
    name,
    setting,
    context,
    CASE context
        WHEN 'postmaster' THEN '서버 재시작 필요'
        WHEN 'sighup'     THEN 'pg_reload_conf() 가능'
        WHEN 'superuser'  THEN 'SET 명령 가능 (슈퍼유저)'
        WHEN 'user'       THEN 'SET 명령 가능 (일반 사용자)'
        ELSE context
    END AS change_method
FROM pg_settings
WHERE name = '변경하려는_파라미터명';

2. 파라미터 변경 로직은 애플리케이션 초기화 단계에서 일괄 처리

세션 파라미터 변경은 커넥션 풀링 설정(pgBouncer, pg_pool-II)의 connect_query 또는 애플리케이션의 커넥션 초기화 훅에서 일괄적으로 처리하세요. 쿼리 실행 도중 임의로 파라미터를 변경하면 트랜잭션 상태에 따라 55P02 에러가 발생할 수 있으며, 코드 유지보수도 어려워집니다.