PostgreSQL transaction_timeout 기준 정리

본문 중간의 쿠팡 추천 상품 구매시 쿠팡 파트너스에서 일정액의 수수료를 제공받습니다.

PostgreSQL transaction_timeout 기준 정리

transaction_timeout은 트랜잭션 상태로 머문 전체 시간을 기준으로 세션을 종료하는 PostgreSQL 설정이다. 2026년 7월 7일 기준 PostgreSQL 18 공식 문서를 보면 명시적인 BEGIN 트랜잭션뿐 아니라 단일 SQL 문이 암묵적으로 만드는 트랜잭션에도 적용되며, 기본값 0은 비활성화다.

실무에서 헷갈리는 지점은 이 값이 statement_timeout, lock_timeout, idle_in_transaction_session_timeout, idle_session_timeout과 무엇이 다른가다. 이 글은 각 타임아웃이 재는 구간과 함께 어떤 상황에서 transaction_timeout을 우선 검토할 만한지 기준 중심으로 정리한다.

transaction_timeout은 무엇을 끊을까?

설정	재는 대상	트리거 시점
transaction_timeout	트랜잭션 전체 수명	트랜잭션 상태가 지정 시간보다 길어질 때
statement_timeout	개별 SQL 문 실행 시간	문장 하나가 오래 걸릴 때
lock_timeout	락 대기 시간	락을 기다리는 구간이 길 때
idle_in_transaction_session_timeout	트랜잭션 안의 유휴 시간	열린 트랜잭션에서 클라이언트 입력 대기가 길 때
idle_session_timeout	트랜잭션 밖의 유휴 시간	세션이 놀고 있을 때

transaction_timeout의 핵심은 "실행 중인지, 락을 기다리는 중인지, 잠깐 멈춰 있는지"를 따지지 않고 트랜잭션 상태 자체가 너무 오래 이어지면 세션을 끝낸다는 점이다. 따라서 긴 트랜잭션 자체를 제한하고 싶을 때 가장 직접적인 제어 수단이다.

공식 문서 기준 동작 범위는 어디까지일까?

PostgreSQL 18 공식 문서는 이 제한이 명시적인 트랜잭션뿐 아니라 단일 SQL 문이 암묵적으로 시작하는 트랜잭션에도 적용된다고 설명한다. 즉, 애플리케이션이 BEGIN을 직접 쓰지 않아도 오래 걸리는 단일 작업이라면 영향을 받을 수 있다.

또 하나 중요한 점은 prepared transaction은 이 타임아웃 대상이 아니라는 점이다. 따라서 2단계 커밋을 쓰는 환경에서는 일반 트랜잭션 보호와 prepared transaction 관리 기준을 따로 봐야 한다.

다른 타임아웃과 같이 걸면 무엇이 우선될까?

공식 문서는 transaction_timeout이 idle_in_transaction_session_timeout 또는 statement_timeout보다 짧거나 같으면 더 긴 쪽은 무시된다고 설명한다. 결국 세션을 더 빨리 끝내는 제한이 있으면 늦게 발동할 제한은 의미가 없다는 뜻이다.

SET statement_timeout = '30s';
SET transaction_timeout = '20s';

이 경우 개별 문장 제한 30초를 두더라도 트랜잭션 전체가 20초를 넘기면 먼저 종료될 수 있다. 반대로 긴 배치 작업에서 문장 하나는 짧지만 트랜잭션 전체가 과도하게 길어지는 문제가 있다면 statement_timeout만으로는 제어가 부족할 수 있다.

언제 유용할까?

상황	검토 이유
애플리케이션 버그로 트랜잭션 종료가 자주 누락될 때	오래 열린 트랜잭션을 상한선으로 제한할 수 있음
문장별 시간보다 트랜잭션 전체 길이가 중요한 배치 작업	짧은 문장이 반복돼도 총 소요 시간을 제한할 수 있음
락 대기와 유휴 상태를 모두 포함해 긴 트랜잭션을 막고 싶을 때	상태 구분 없이 전체 트랜잭션 수명을 본다는 점이 맞음

반대로 세션 풀러나 미들웨어가 예기치 않은 연결 종료에 민감한 환경이라면 타임아웃을 넓게 잡거나 사용자·역할 단위로 제한하는 편이 안전하다. PostgreSQL 문서도 이런 종류의 타임아웃을 전역 postgresql.conf에 두는 방식은 모든 세션에 영향을 주므로 권장하지 않는다.

 

 

idle_in_transaction_session_timeout과는 어떻게 다를까?

idle_in_transaction_session_timeout은 열린 트랜잭션에서 클라이언트 질의를 기다리는 유휴 시간만 본다. 그래서 질의 실행 중이거나 락을 기다리는 동안에는 그 자체로 발동 기준이 되지 않는다.

반면 transaction_timeout은 트랜잭션이 시작된 뒤 끝날 때까지의 전체 시간을 본다. 실무 기준으로 정리하면, "가만히 방치된 트랜잭션"이 문제면 idle_in_transaction_session_timeout, "어떤 이유로든 너무 오래 사는 트랜잭션"이 문제면 transaction_timeout이 더 직접적이다.

lock_timeout, statement_timeout만으로 부족한 경우는?

lock_timeout은 락을 기다리는 구간에만 걸리고, statement_timeout은 개별 문장 기준이다. 예를 들어 문장 하나하나는 5초 안에 끝나지만 같은 트랜잭션이 수백 개 문장을 묶어서 10분 이상 지속된다면 둘 다 크게 문제를 드러내지 못할 수 있다.

이런 패턴에서는 transaction_timeout이 트랜잭션 상한선을 명확하게 만든다. 다만 너무 짧게 잡으면 정상적인 대량 처리나 마이그레이션도 잘릴 수 있으므로, 운영 배치와 온라인 요청의 성격을 구분해 적용 범위를 나누는 편이 맞다.

운영에서 무난한 적용 기준

대상	무난한 접근	이유
웹 요청용 역할	역할 또는 세션 단위로 제한 검토	짧은 트랜잭션이 기대되므로 보호 효과가 큼
배치·마이그레이션 역할	별도 역할 정책 또는 더 긴 값 사용	정상 작업이 오래 걸릴 수 있음
전역 기본값	신중하게 사용	PostgreSQL 문서도 전체 세션 영향 때문에 권장하지 않음

자주 헷갈리는 질문

Q. transaction_timeout은 락 대기 시간만 재나?

아니다. 락 대기, 실행, 유휴 상태를 따로 나누지 않고 트랜잭션 전체 시간을 본다. 락 대기만 제한하려면 lock_timeout이 더 직접적이다.

Q. 단일 SQL 문에도 적용되나?

적용된다. PostgreSQL 18 공식 문서는 단일 문장에 대응하는 암묵적 트랜잭션에도 이 제한이 적용된다고 설명한다.

Q. prepared transaction에도 적용되나?

아니다. 공식 문서의 주석은 prepared transaction은 이 타임아웃 대상이 아니라고 명시한다.

정리

transaction_timeout은 개별 문장이나 특정 대기 구간이 아니라 트랜잭션 전체 수명을 제한하는 설정이다. 그래서 오래 살아남는 트랜잭션 자체를 줄이고 싶을 때 가장 먼저 비교할 값이다.

2026년 7월 7일 기준 PostgreSQL 18 공식 문서만 놓고 보면, 무난한 기준은 전역 기본값보다 역할·세션 단위 적용을 우선 검토하고, statement_timeout이나 idle_in_transaction_session_timeout과의 우선순위를 함께 설계하는 것이다.

참고 자료

• PostgreSQL 18 공식 문서: Client Connection Defaults