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

40003
2026년 07월 03일 | DBMS Error 가이드

이 글에서 다루는 내용

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

40003 statement completion unknown 는?

PostgreSQL 에러 코드 40003 (statement_completion_unknown)은 트랜잭션 내에서 특정 명령문(statement)의 완료 여부를 데이터베이스가 확실히 알 수 없는 상태가 되었을 때 발생합니다. 주로 네트워크 단절, 서버 크래시, 또는 연결 타임아웃 등의 외부 요인으로 인해 트랜잭션이 커밋되었는지 롤백되었는지 확인할 수 없는 불확실한 상태(in-doubt transaction)에 빠졌을 때 나타납니다. 이 에러는 SQLSTATE 클래스 40(Transaction Rollback)에 속하며, 데이터 무결성 보장을 위해 반드시 애플리케이션 레벨에서 적절한 재시도 로직과 확인 절차를 갖추어야 합니다.

주요 발생 원인

1. 네트워크 단절 또는 연결 타임아웃

트랜잭션이 진행 중인 도중 클라이언트와 PostgreSQL 서버 사이의 네트워크 연결이 갑자기 끊어지면, 서버는 해당 트랜잭션의 최종 상태(커밋 또는 롤백)를 클라이언트에 전달하지 못한 채 종료될 수 있습니다. 이 경우 클라이언트 입장에서는 명령문이 성공적으로 완료되었는지 알 수 없으며, PostgreSQL은 40003 에러를 통해 이 불확실성을 알립니다. 특히 클라우드 환경이나 고가용성(HA) 구성에서 페일오버(failover)가 발생할 때 자주 나타납니다.

2. 서버 크래시 및 비정상 종료

PostgreSQL 서버가 명령문 실행 도중 비정상적으로 종료(OOM Killer, 하드웨어 장애 등)되면, WAL(Write-Ahead Log)에 기록이 완료되었는지 여부가 불분명해질 수 있습니다. 서버가 재시작된 후에도 해당 트랜잭션이 실제로 디스크에 반영되었는지 클라이언트가 확인하기 어렵습니다. 이는 특히 synchronous_commit = off 설정이나 비동기 복제 환경에서 더욱 위험하게 작용합니다.

3. 2단계 커밋(Two-Phase Commit) 과정에서의 불확실 트랜잭션

분산 트랜잭션 처리를 위해 PREPARE TRANSACTION / COMMIT PREPARED를 사용하는 환경에서, 준비(PREPARE) 이후 커밋 메시지가 유실되면 트랜잭션이 “in-doubt” 상태로 남아 40003 에러를 유발할 수 있습니다. 이런 상황은 미들웨어(예: JTA, XA 트랜잭션)를 사용하는 엔터프라이즈 환경에서 자주 발생하며, pg_prepared_xacts 뷰를 통해 확인할 수 있습니다.

해결 방법

원인 1: 네트워크 단절 후 트랜잭션 상태 확인

연결 복구 후 가장 먼저 해야 할 일은 트랜잭션이 실제로 반영되었는지 데이터를 직접 조회하여 확인하는 것입니다.

-- 트랜잭션 완료 여부를 데이터로 직접 확인
-- 예: 주문 INSERT 후 네트워크 단절이 발생한 경우
SELECT order_id, status, created_at
FROM orders
WHERE order_id = 12345
  AND created_at >= NOW() - INTERVAL '5 minutes';

-- 결과가 존재하면 커밋 완료, 없으면 재시도 필요
-- 재시도 시 중복 방지를 위해 UPSERT 사용 권장
INSERT INTO orders (order_id, user_id, status, amount, created_at)
VALUES (12345, 999, 'pending', 50000, NOW())
ON CONFLICT (order_id) DO NOTHING;

-- 또는 멱등성(idempotency) 키를 활용한 재시도
INSERT INTO orders (order_id, user_id, status, amount, idempotency_key, created_at)
VALUES (12345, 999, 'pending', 50000, 'unique-uuid-key-abc123', NOW())
ON CONFLICT (idempotency_key) DO NOTHING;

원인 2: 서버 재시작 후 in-doubt 트랜잭션 처리

서버가 재시작된 후에는 WAL 상태와 실제 데이터를 비교하여 트랜잭션 완료 여부를 판단합니다.

-- 현재 열려있는 트랜잭션 확인 (서버 재시작 후)
SELECT pid, usename, application_name, state, query_start, query
FROM pg_stat_activity
WHERE state != 'idle'
  AND query_start < NOW() - INTERVAL '10 minutes';

-- 장기 미완료 트랜잭션 강제 종료 (주의: 롤백됨)
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state = 'idle in transaction'
  AND query_start < NOW() - INTERVAL '30 minutes';

-- 트랜잭션 ID로 커밋 여부 확인
SELECT txid_status(1234567);
-- 결과: 'committed', 'aborted', 'in progress', 또는 NULL(알 수 없음)

원인 3: 2단계 커밋 in-doubt 트랜잭션 해결

-- in-doubt 상태의 prepared 트랜잭션 목록 조회
SELECT gid, prepared, owner, database, transaction
FROM pg_prepared_xacts
ORDER BY prepared;

-- in-doubt 트랜잭션의 상태를 외부 트랜잭션 관리자와 대조 후 결정
-- 커밋이 확실한 경우
COMMIT PREPARED 'txn_20240101_12345';

-- 롤백이 필요한 경우
ROLLBACK PREPARED 'txn_20240101_12345';

-- 오래된 prepared 트랜잭션 일괄 확인 (1시간 이상 경과)
SELECT gid, prepared, owner,
       EXTRACT(EPOCH FROM (NOW() - prepared)) / 60 AS minutes_pending
FROM pg_prepared_xacts
WHERE prepared < NOW() - INTERVAL '1 hour'
ORDER BY prepared;

애플리케이션 레벨 재시도 로직 예시

-- 재시도 안전한 함수 작성 예시 (PL/pgSQL)
CREATE OR REPLACE FUNCTION safe_insert_order(
    p_order_id BIGINT,
    p_user_id INT,
    p_amount NUMERIC,
    p_idempotency_key UUID
) RETURNS TEXT AS $$
DECLARE
    v_result TEXT;
BEGIN
    INSERT INTO orders (order_id, user_id, amount, idempotency_key, status, created_at)
    VALUES (p_order_id, p_user_id, p_amount, p_idempotency_key, 'pending', NOW())
    ON CONFLICT (idempotency_key) DO UPDATE
        SET updated_at = NOW()
    RETURNING status INTO v_result;

    RETURN COALESCE(v_result, 'already_exists');
EXCEPTION
    WHEN others THEN
        RAISE WARNING 'Order insert failed: %', SQLERRM;
        RETURN 'error: ' || SQLERRM;
END;
$$ LANGUAGE plpgsql;

-- 사용 예시
SELECT safe_insert_order(12345, 999, 50000.00, gen_random_uuid());

예방 방법

1. 멱등성(Idempotency) 설계 및 synchronous_commit 설정 강화

모든 쓰기 작업에 고유한 멱등성 키(UUID 또는 비즈니스 키)를 부여하고, ON CONFLICT DO NOTHING 또는 ON CONFLICT DO UPDATE 패턴을 적극적으로 활용하세요. 이렇게 하면 네트워크 단절 후 재시도를 해도 데이터 중복이 발생하지 않습니다. 또한 데이터 안전성이 중요한 서비스에서는 postgresql.conf에서 synchronous_commit = on(기본값)을 유지하고, 성능이 필요한 경우에도 최소한 synchronous_commit = local로 설정하여 로컬 WAL 기록을 보장하세요.

-- 세션 레벨로 동기 커밋 강제 설정
SET synchronous_commit = on;

-- 멱등성 키 컬럼에 고유 제약 조건 추가
ALTER TABLE orders ADD COLUMN idempotency_key UUID UNIQUE;
CREATE UNIQUE INDEX idx_orders_idempotency ON orders(idempotency_key)
WHERE idempotency_key IS NOT NULL;

2. 모니터링 및 pg_prepared_xacts 정기 점검 자동화

2단계 커밋을 사용하는 환경에서는 pg_prepared_xacts 뷰를 주기적으로 모니터링하여 오래된 in-doubt 트랜잭션을 자동으로 감지하고 알람을 발생시키는 시스템을 구축하세요. 또한 idle_in_transaction_session_timeout 파라미터를 설정하여 오래된 유휴 트랜잭션이 자동으로 종료되도록 관리하면 40003 에러의 파급 효과를 최소화할 수 있습니다.

-- postgresql.conf 권장 설정
-- idle_in_transaction_session_timeout = '5min'
-- lock_timeout = '30s'
-- statement_timeout = '60s'

-- 현재 세션에 적용
SET idle_in_transaction_session_timeout = '300000'; -- 5분 (ms 단위)
SET lock_timeout = '30000';                         -- 30초

-- 모니터링 쿼리: 5분 이상 지속된 prepared 트랜잭션 알람
SELECT COUNT(*) AS stale_prepared_count
FROM pg_prepared_xacts
WHERE prepared < NOW() - INTERVAL '5 minutes';