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

25P03 idle in transaction session timeout 는?

PostgreSQL 에러 코드 25P03은 트랜잭션이 시작된 후 아무런 작업 없이 일정 시간 이상 대기 상태(idle in transaction)로 머물렀을 때 서버가 강제로 해당 세션을 종료하면서 발생하는 에러입니다. 쉽게 말해, BEGIN 또는 START TRANSACTION으로 트랜잭션을 열어 놓은 채 쿼리를 실행하지 않고 방치된 세션을 PostgreSQL이 자동으로 끊어버리는 것입니다. 이 에러는 idle_in_transaction_session_timeout 파라미터에 설정된 시간(밀리초 단위)이 초과될 때 트리거되며, 장기간 열린 트랜잭션으로 인한 락(Lock) 점유, 테이블 팽창(Table Bloat), 리소스 낭비 등의 문제를 방지하기 위한 PostgreSQL의 안전 장치입니다.

---

주요 발생 원인

1. 애플리케이션 코드에서 트랜잭션을 닫지 않은 채 대기

가장 흔한 원인으로, 애플리케이션이 BEGIN으로 트랜잭션을 시작한 뒤 비즈니스 로직 처리, 외부 API 호출, 사용자 입력 대기 등 DB와 무관한 작업을 수행하는 동안 트랜잭션이 열린 채 방치되는 경우입니다. 예를 들어 결제 처리 로직에서 트랜잭션을 열고 외부 PG사 API 응답을 기다리는 동안 DB 커넥션이 idle in transaction 상태로 굳어버리는 패턴이 대표적입니다. 이 상태는 테이블에 불필요한 락을 유지하게 만들어 다른 쿼리의 처리를 차단하는 심각한 성능 문제로 이어집니다.

2. 커넥션 풀(Connection Pool)의 잘못된 설정 및 관리

PgBouncer, HikariCP 등의 커넥션 풀러를 사용할 때 커넥션 재사용 과정에서 이전 트랜잭션이 COMMIT 또는 ROLLBACK 없이 풀에 반환되는 경우가 있습니다. 이 경우 커넥션 풀러는 해당 커넥션이 정상이라고 판단하지만, PostgreSQL 서버 입장에서는 여전히 트랜잭션이 열려 있는 idle in transaction 상태로 인식됩니다. 결과적으로 idle_in_transaction_session_timeout에 의해 해당 커넥션이 강제 종료되고, 커넥션 풀에는 끊어진 커넥션이 남아 다음 요청에서 예상치 못한 에러가 연쇄 발생할 수 있습니다.

3. ORM 또는 드라이버의 자동 트랜잭션 관리 미숙

Django ORM, SQLAlchemy, JPA/Hibernate 등 많은 ORM 프레임워크는 기본적으로 자동 트랜잭션 관리 기능을 제공합니다. 설정이나 코드 실수로 인해 autocommit이 비활성화된 상태에서 단순 SELECT 쿼리조차 트랜잭션 내에서 실행되고, 이후 명시적으로 커밋/롤백하지 않으면 해당 세션이 idle in transaction으로 남게 됩니다. 특히 배치 작업이나 긴 루프 처리 중에 ORM 세션을 재활용할 때 이러한 패턴이 자주 나타납니다.

---

해결 방법

원인 1 해결: 현재 idle in transaction 세션 파악 및 강제 종료

먼저 현재 문제가 되는 세션을 확인합니다.

-- idle in transaction 상태인 세션 조회 (5분 이상 경과)
SELECT
    pid,
    usename,
    application_name,
    client_addr,
    state,
    state_change,
    now() - state_change AS idle_duration,
    query
FROM pg_stat_activity
WHERE state = 'idle in transaction'
  AND state_change < now() - INTERVAL '5 minutes'
ORDER BY idle_duration DESC;

문제가 되는 세션을 확인했다면 강제 종료합니다.

-- 특정 PID의 세션을 안전하게 종료 (진행 중인 트랜잭션은 롤백됨)
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state = 'idle in transaction'
  AND state_change < now() - INTERVAL '5 minutes';

원인 2 해결: idle_in_transaction_session_timeout 설정

서버 레벨 또는 세션/역할 레벨에서 타임아웃을 적절히 설정합니다.

-- postgresql.conf 또는 ALTER SYSTEM으로 전역 설정 (단위: 밀리초)
-- 예: 5분(300,000ms)으로 설정
ALTER SYSTEM SET idle_in_transaction_session_timeout = '300000';

-- 설정 즉시 반영
SELECT pg_reload_conf();

-- 현재 설정값 확인
SHOW idle_in_transaction_session_timeout;

-- 특정 역할(Role)에만 적용
ALTER ROLE app_user SET idle_in_transaction_session_timeout = '120000';

-- 특정 데이터베이스에만 적용
ALTER DATABASE myapp_db SET idle_in_transaction_session_timeout = '300000';

원인 3 해결: 애플리케이션 레벨에서 트랜잭션 명시적 제어

-- 올바른 트랜잭션 패턴 (외부 작업 전 커밋/롤백 처리)
BEGIN;

-- 필요한 DB 작업 수행
UPDATE orders SET status = 'processing' WHERE order_id = 12345;
INSERT INTO order_logs (order_id, action, created_at)
VALUES (12345, 'status_changed', NOW());

-- 외부 API 호출 전 반드시 커밋 처리
COMMIT;

-- 외부 API 호출은 트랜잭션 밖에서 수행

-- 잘못된 패턴 방지: 트랜잭션 내부에서 긴 작업 금지
-- BEGIN;
-- UPDATE orders SET status = 'processing' WHERE order_id = 12345;
-- [외부 API 호출 - 수십 초 소요] <- 절대 금지
-- COMMIT;

-- statement_timeout과 함께 사용하여 이중 보호
SET idle_in_transaction_session_timeout = '60000';  -- 1분
SET statement_timeout = '30000';                     -- 30초

---

예방 방법

1. 모니터링 및 알림 체계 구축

pg_stat_activity 뷰를 주기적으로 폴링하여 idle in transaction 세션이 임계값을 초과하면 즉시 알림을 발송하는 모니터링 체계를 구축하세요. 아래 쿼리를 크론잡(cron job) 또는 모니터링 도구(Prometheus, Grafana, Datadog)에 연동하면 장애 발생 전 선제적으로 대응할 수 있습니다.

-- 모니터링용 쿼리: idle in transaction 세션 카운트 및 최대 대기 시간
SELECT
    COUNT(*) AS idle_in_transaction_count,
    MAX(EXTRACT(EPOCH FROM (now() - state_change))) AS max_idle_seconds,
    MAX(EXTRACT(EPOCH FROM (now() - xact_start)))   AS max_xact_seconds
FROM pg_stat_activity
WHERE state = 'idle in transaction';

2. 애플리케이션 커넥션 풀 설정 검토 및 autocommit 강제 활성화

커넥션 풀 설정에서 connection_timeout, idle_timeout, max_lifetime 등의 값을 idle_in_transaction_session_timeout보다 짧게 설정하여 PostgreSQL이 강제 종료하기 전에 풀러가 먼저 커넥션을 정리하도록 합니다. 또한 단순 읽기 작업이나 명시적인 트랜잭션 관리가 필요 없는 경우 반드시 autocommit=True를 사용하는 습관을 들이고, ORM 사용 시 트랜잭션 범위(Scope)를 최소화하는 코딩 가이드라인을 팀 내에 공유하세요.

---

관련 에러

• 25P02 (in_failed_sql_transaction): 트랜잭션 내에서 이미 에러가 발생하여 실패한 상태에서 추가 쿼리를 실행하려 할 때 발생합니다. idle in transaction (aborted) 상태와 연관이 깊습니다.
• 57P01 (admin_shutdown): 관리자가 서버를 종료할 때 세션이 강제 종료되며 발생하는 에러로, 25P03처럼 예상치 못한 세션 종료 상황에서 애플리케이션이 받게 되는 에러입니다.
• 57014 (query_canceled): statement_timeout 초과로 쿼리가 취소될 때 발생하며, 25P03과 함께 타임아웃 관련 에러로 묶어서 처리 로직을 구성하는 것이 좋습니다.
• 08006 (connection_failure): 25P03으로 세션이 강제 종료된 후 커넥션 풀러가 해당 커넥션을 재사용하려 할 때 클라이언트 측에서 발생할 수 있는 연결 실패 에러입니다.

---

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