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

40003 statement completion unknown 는?

PostgreSQL 에러 코드 40003 (statement_completion_unknown)은 트랜잭션 내에서 특정 구문(statement)의 완료 여부를 데이터베이스가 확인할 수 없는 상태에 빠졌을 때 발생합니다. 이는 주로 네트워크 장애, 서버 크래시, 또는 타임아웃으로 인해 클라이언트와 서버 간의 통신이 비정상적으로 끊어지면서 트랜잭션의 커밋 또는 롤백 결과를 알 수 없는 불확실한(ambiguous) 상태가 됩니다. 실무에서는 특히 고부하 환경이나 장기 실행 트랜잭션(long-running transaction)에서 자주 마주치게 되며, 데이터 무결성을 위협할 수 있는 심각한 상황으로 취급해야 합니다.

---

주요 발생 원인

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

가장 흔한 원인으로, 클라이언트가 COMMIT 또는 ROLLBACK 명령을 전송한 직후 네트워크가 끊어지는 경우입니다. 서버는 해당 구문을 처리했는지 여부를 클라이언트에 알릴 수 없고, 클라이언트 역시 서버의 응답을 받지 못해 트랜잭션의 실제 완료 여부를 알 수 없는 상황이 발생합니다. 특히 클라우드 환경이나 VPN, 방화벽이 개입된 네트워크에서 tcp_keepalives_idle 설정이 너무 길 경우 자주 발생합니다.

2. PostgreSQL 서버 또는 프로세스의 비정상 종료 (Crash)

백엔드 프로세스(postmaster 자식 프로세스)가 OOM Killer, 세그멘테이션 폴트, 또는 강제 kill -9 등으로 비정상 종료되면 현재 진행 중인 트랜잭션의 완료 여부가 불분명해집니다. PostgreSQL의 WAL(Write-Ahead Logging) 메커니즘이 복구를 지원하지만, 클라이언트 입장에서는 COMMIT이 실제로 디스크에 반영되었는지 확인하기 전에 연결이 끊어지면 40003 에러에 해당하는 상황이 됩니다. 이 경우 pg_log와 WAL 로그를 함께 분석해야 정확한 상태를 파악할 수 있습니다.

3. 애플리케이션 레벨의 연결 풀(Connection Pool) 문제

PgBouncer, pgpool-II 등의 연결 풀러가 트랜잭션 중간에 연결을 강제로 재사용하거나, 세션 레벨 트랜잭션 풀링(session-level pooling)이 아닌 트랜잭션 레벨 풀링(transaction-level pooling) 설정에서 잘못된 연결 관리가 이루어질 때 발생합니다. 연결 풀러가 아직 트랜잭션이 종료되지 않은 연결을 다른 클라이언트에 할당하거나, idle-in-transaction 타임아웃이 만료되어 연결을 끊어버리면 클라이언트는 구문 완료 여부를 확인할 수 없게 됩니다.

---

해결 방법

원인 1: 네트워크 단절 대응

먼저 현재 활성 트랜잭션 및 잠금 상태를 확인합니다.

-- 현재 진행 중인 트랜잭션과 상태 확인
SELECT
    pid,
    usename,
    application_name,
    client_addr,
    state,
    query_start,
    state_change,
    wait_event_type,
    wait_event,
    query
FROM pg_stat_activity
WHERE state != 'idle'
ORDER BY query_start;

-- idle in transaction 상태가 오래된 세션 확인
SELECT
    pid,
    now() - state_change AS duration,
    query,
    state
FROM pg_stat_activity
WHERE state = 'idle in transaction'
  AND state_change < now() - INTERVAL '5 minutes';

불확실한 트랜잭션이 확인된 경우 해당 프로세스를 안전하게 종료합니다.

-- 특정 PID의 쿼리를 안전하게 취소 (SIGINT)
SELECT pg_cancel_backend(pid)
FROM pg_stat_activity
WHERE state = 'idle in transaction'
  AND state_change < now() - INTERVAL '10 minutes';

-- 강제 종료가 필요할 경우 (SIGTERM)
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state = 'idle in transaction'
  AND state_change < now() - INTERVAL '10 minutes';

postgresql.conf에서 타임아웃 설정을 조정합니다.

-- 현재 타임아웃 설정 확인
SHOW idle_in_transaction_session_timeout;
SHOW statement_timeout;
SHOW lock_timeout;

-- 세션 레벨에서 idle in transaction 타임아웃 설정 (5분)
SET idle_in_transaction_session_timeout = '5min';

-- TCP 킵얼라이브 관련 파라미터 확인
SHOW tcp_keepalives_idle;
SHOW tcp_keepalives_interval;
SHOW tcp_keepalives_count;

원인 2: 서버 크래시 후 복구 확인

서버 재시작 후 트랜잭션이 실제로 커밋되었는지 WAL 및 데이터를 확인합니다.

-- pg_xact(트랜잭션 커밋 로그) 기반으로 트랜잭션 상태 확인
-- txid_current()로 현재 트랜잭션 ID 조회
SELECT txid_current();

-- 특정 트랜잭션 ID의 상태 확인
SELECT txid_status(트랜잭션_ID);
-- 반환값: 'committed', 'aborted', 'in progress', NULL(알 수 없음)

-- 예시
SELECT txid_status(12345);

애플리케이션에서 재시도 로직을 포함한 트랜잭션 패턴을 적용합니다.

-- 멱등성(idempotency)을 보장하는 UPSERT 패턴 사용
INSERT INTO orders (order_id, customer_id, amount, status)
VALUES (1001, 42, 15000, 'pending')
ON CONFLICT (order_id)
DO UPDATE SET
    status = EXCLUDED.status,
    updated_at = now()
WHERE orders.status != 'completed';

-- 트랜잭션 내 저장점(SAVEPOINT) 활용으로 부분 롤백 가능하게 구성
BEGIN;
  SAVEPOINT before_critical_update;

  UPDATE accounts SET balance = balance - 10000 WHERE account_id = 1;

  -- 에러 발생 시 저장점으로 롤백
  SAVEPOINT after_debit;

  UPDATE accounts SET balance = balance + 10000 WHERE account_id = 2;

COMMIT;

원인 3: 연결 풀 설정 교정

연결 풀 관련 설정을 확인하고, 트랜잭션 상태를 주기적으로 모니터링합니다.

-- 연결 풀에서 들어온 연결의 실제 상태 확인
SELECT
    pid,
    usename,
    application_name,
    client_addr,
    backend_type,
    state,
    query
FROM pg_stat_activity
WHERE application_name LIKE '%pgbouncer%'
   OR application_name LIKE '%pgpool%'
ORDER BY state;

-- 잠금 대기로 인한 블로킹 상황 확인
SELECT
    blocked.pid AS blocked_pid,
    blocked.query AS blocked_query,
    blocking.pid AS blocking_pid,
    blocking.query AS blocking_query
FROM pg_stat_activity AS blocked
JOIN pg_stat_activity AS blocking
  ON blocking.pid = ANY(pg_blocking_pids(blocked.pid))
WHERE cardinality(pg_blocking_pids(blocked.pid)) > 0;

---

예방 방법

1. idle_in_transaction_session_timeout 및 statement_timeout 전역 설정

postgresql.conf에 다음과 같이 설정하여 미완료 트랜잭션이 무기한 열려있는 상황을 방지합니다. 이 설정은 모든 세션에 기본 적용되므로, 장기 배치 작업이 있다면 해당 세션에서만 별도로 값을 늘려주는 방식으로 예외 처리합니다.

-- postgresql.conf 또는 ALTER SYSTEM으로 전역 설정
ALTER SYSTEM SET idle_in_transaction_session_timeout = '3min';
ALTER SYSTEM SET statement_timeout = '30min';
ALTER SYSTEM SET lock_timeout = '30s';
SELECT pg_reload_conf();

-- 특정 롤(role)에 대해서만 타임아웃 조정
ALTER ROLE batch_user SET statement_timeout = '2h';
ALTER ROLE batch_user SET idle_in_transaction_session_timeout = '30min';

2. 애플리케이션 레벨의 트랜잭션 재시도 로직과 txid_status() 활용

40003 에러가 발생했을 때 맹목적으로 재시도(retry)하면 중복 처리가 발생할 수 있습니다. 반드시 txid_status()를 통해 이전 트랜잭션의 완료 여부를 먼저 확인한 후 재시도 여부를 결정해야 합니다. 또한 모든 DML 작업은 멱등성(idempotency)을 보장하도록 설계하고, 재시도 횟수에 지수 백오프(exponential backoff)를 적용하는 것이 Best Practice입니다.

-- 재시도 전 이전 트랜잭션 상태 확인 예시
-- 애플리케이션에서 저장해둔 txid를 사용
SELECT txid_status(저장된_트랜잭션_ID);
-- 'committed' → 재시도 불필요 (이미 성공)
-- 'aborted'   → 안전하게 재시도 가능
-- NULL        → 트랜잭션 ID가 너무 오래되어 알 수 없음 (pg_xact 파기)
-- 'in progress' → 대기 후 재확인

---

관련 에러

• 40001 (serialization_failure): SERIALIZABLE 또는 REPEATABLE READ 격리 수준에서 직렬화 충돌이 발생할 때 나타나며, 40003과 마찬가지로 트랜잭션 재시도 로직이 필요합니다.
• 40P01 (deadlock_detected): 두 개 이상의 트랜잭션이 서로의 잠금을 기다리는 교착 상태로, PostgreSQL이 자동으로 하나의 트랜잭션을 희생(victim)시켜 롤백합니다. 40003과 함께 발생할 수 있습니다.
• 08006 (connection_failure) / 08001 (sqlclient_unable_to_establish_sqlconnection): 네트워크 레벨의 연결 실패 에러로, 40003이 발생하는 근본 원인이 되는 경우가 많습니다.
• 57P01 (admin_shutdown) / 57P02 (crash_shutdown): 서버 관리자에 의한 종료 또는 크래시로 인한 종료로, 진행 중인 트랜잭션이 40003 상태로 남을 수 있습니다.

---

본 포스트는 AI가 생성한 기술 가이드입니다. 운영 환경 적용 전 충분한 검토를 권장합니다.