PostgreSQL statement_timeout 기준 정리

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

PostgreSQL statement_timeout 기준 정리

statement_timeout은 PostgreSQL이 너무 오래 걸리는 SQL 문장을 언제 중단할지 정하는 제한 시간이다. 2026년 6월 16일 기준 PostgreSQL current 공식 문서는 PostgreSQL 18 문서이며, 이 문서에서 statement_timeout 기본값은 0으로 안내된다. 즉 기본 상태에서는 시간 제한 없이 문장을 실행한다.

실무에서는 이 값을 전역으로 바로 켜도 되는지, lock_timeout이나 idle_in_transaction_session_timeout과 무엇이 다른지, 세션 단위와 역할 단위 중 어디에 두는 편이 안전한지가 자주 헷갈린다. 이 글은 PostgreSQL 공식 문서 기준으로 statement_timeout의 의미, 적용 범위, 관련 timeout과의 차이, 무난한 적용 기준을 정리한다.

statement_timeout은 무엇을 제한할까?

공식 문서에서 statement_timeout은 지정된 시간보다 오래 걸리는 statement를 중단하는 설정으로 설명된다. 단위를 생략하면 밀리초로 해석되고, 0은 timeout 비활성화다.

핵심은 이 값이 세션 전체 시간을 재는 것이 아니라 개별 SQL 문장의 서버 처리 시간을 기준으로 동작한다는 점이다. 오래 걸리는 조회, 대기 중인 갱신, 비효율적인 집계처럼 한 문장이 오래 붙잡고 있으면 그 문장을 중단한다.

기본값과 공식 문서 기준 동작은?

항목	공식 문서 기준	실무 해석
기본값	0	기본 상태에서는 timeout이 없다.
단위 생략	밀리초	5000은 5초와 같다.
simple query protocol	쿼리 문자열 안의 각 statement마다 따로 적용	세미콜론으로 여러 문장을 보내면 각 문장을 개별로 잰다.
extended query protocol	query 관련 메시지가 도착할 때 시작되고 Execute 또는 Sync 완료 시 취소	드라이버 동작 방식에 따라 체감 범위가 달라질 수 있다.

공식 문서는 PostgreSQL 13 이전에는 simple query 문자열 전체에 timeout을 적용하는 경우가 많았지만, 현재 문서 기준으로는 하나의 simple-query message 안에 여러 SQL 문장이 있어도 각 statement에 개별 적용된다고 설명한다.

전역 설정으로 바로 넣는 것이 왜 조심스러울까?

공식 문서는 statement_timeout을 postgresql.conf에 두는 것은 권장하지 않는다고 명시한다. 이유는 모든 세션에 영향을 주기 때문이다.

이 문장 하나만으로도 운영 기준이 분명해진다. 배치 작업, 마이그레이션, 분석 쿼리, 관리 세션까지 같은 제한을 받으면 예상보다 넓은 범위에서 중단이 발생할 수 있다. 따라서 대부분의 환경에서는 먼저 세션, 역할, 또는 특정 데이터베이스 범위에서 좁게 적용하는 편이 더 안전하다.

어디에 적용하는 것이 무난할까?

공식 문서 기준으로 SET은 현재 세션에만 영향을 준다. 또한 ALTER ROLE ... SET과 ALTER DATABASE ... SET은 이후 새로 시작되는 세션의 기본값을 바꾼다.

• 애플리케이션 연결 하나만 시험할 때: SET statement_timeout = '5s'처럼 세션 단위 적용이 가장 안전하다.
• 특정 애플리케이션용 DB 계정이 분리돼 있을 때: ALTER ROLE ... SET으로 역할 단위 기본값을 주는 편이 운영 경계를 나누기 쉽다.
• 하나의 데이터베이스 전체에 공통 정책이 필요할 때: ALTER DATABASE ... SET을 검토할 수 있다.
• 서버 전체 기본값을 한 번에 바꿀 때: 공식 문서가 비권장하므로 신중해야 한다.

SET statement_timeout = '5s';

ALTER ROLE app_user SET statement_timeout = '5s';

ALTER DATABASE app_db SET statement_timeout = '5s';

lock_timeout, idle_in_transaction_session_timeout, transaction_timeout과는 무엇이 다를까?

statement_timeout은 문장 전체 실행 시간을 본다. 반면 lock_timeout은 락을 기다리는 시간만 본다. 공식 문서는 statement_timeout이 0이 아닌데 lock_timeout을 그보다 같거나 더 크게 두는 것은 실익이 적다고 설명한다. 먼저 statement_timeout이 발동하기 때문이다.

idle_in_transaction_session_timeout은 열린 트랜잭션 안에서 클라이언트 질의를 기다리며 idle 상태로 머무는 세션을 종료한다. 이는 긴 statement를 끊는 용도가 아니라, 열린 트랜잭션이 vacuum을 방해하거나 락을 오래 잡는 상황을 줄이기 위한 설정이다.

transaction_timeout은 트랜잭션 전체 지속 시간을 제한한다. 공식 문서는 이 값이 idle_in_transaction_session_timeout이나 statement_timeout보다 짧거나 같으면 더 긴 timeout은 무시된다고 설명한다. 따라서 세 값을 같이 둘 때는 무엇을 먼저 끊고 싶은지 기준을 분명히 해야 한다.

 

 

대부분의 서비스에서는 어떤 기준으로 시작하면 될까?

공식 문서는 구체적인 초 단위 기본값을 강제하지 않는다. 따라서 절대값을 일반론으로 단정하는 대신, 애플리케이션 응답 기대치와 예외 작업의 존재 여부를 먼저 봐야 한다.

• 온라인 요청 중심 서비스: 애플리케이션 계정에만 보수적인 statement_timeout을 두고, 배치 계정은 분리하는 구성이 무난하다.
• 운영 콘솔과 배치가 같은 계정을 쓰는 환경: 전역 적용보다 세션 단위 적용부터 시작하는 편이 안전하다.
• 긴 분석 쿼리가 필요한 환경: 짧은 timeout을 공통 기본값으로 두면 운영자 쿼리까지 자주 중단될 수 있다.
• 락 대기가 문제인 환경: statement_timeout만 올리기보다 lock_timeout과 함께 역할을 나눠서 봐야 한다.

자주 헷갈리는 질문

1. statement_timeout을 걸면 락 대기도 포함될까?

포함된다. statement_timeout은 statement가 서버에 도착해 완료될 때까지를 본다. 락 대기만 따로 제한하고 싶다면 lock_timeout이 더 직접적인 설정이다.

2. 세미콜론으로 여러 문장을 한 번에 보내면 전체 합산으로 재나?

현재 공식 문서 기준으로 simple-query message 안의 각 statement에 개별 적용된다. 다만 PostgreSQL 13 이전에는 전체 query string처럼 취급하는 경우가 많았다는 설명도 함께 확인할 수 있다.

3. 이미 접속 중인 세션에도 ALTER ROLE SET이 바로 적용될까?

아니다. 공식 문서는 역할이나 데이터베이스 기본값 변경이 이후 새로 시작되는 세션의 기본값이 된다고 설명한다. 이미 연결된 세션은 다시 접속해야 새 기본값을 받는다.

FAQ

Q. 모든 서버에 공통으로 5초를 넣어도 될까?

공식 문서는 서버 전체 postgresql.conf 설정을 권장하지 않는다. 같은 수치라도 웹 요청용 계정과 분석용 계정의 요구가 다를 수 있으므로, 범위를 좁혀 적용하는 편이 더 안전하다.

Q. statement_timeout만 있으면 idle 트랜잭션 문제도 해결될까?

아니다. 열린 트랜잭션 안에서 아무 질의도 보내지 않고 대기하는 문제는 idle_in_transaction_session_timeout이 직접 다루는 영역이다.

Q. timeout이 나면 로그에 SQL이 남을까?

공식 문서는 log_min_error_statement가 ERROR 이하이면 timeout이 난 statement도 함께 기록된다고 설명한다.

정리

statement_timeout은 오래 걸리는 SQL 문장을 중단하는 안전장치이고, 2026년 6월 16일 기준 PostgreSQL current 공식 문서에서는 기본값을 0으로 설명한다. 핵심 판단 기준은 서버 전체 공통값을 둘지보다, 어떤 세션과 역할에만 적용할지를 먼저 좁히는 것이다.

대부분의 운영 환경에서는 postgresql.conf 전역값보다 세션, 역할, 데이터베이스 단위 설정이 더 예측 가능하다. 그리고 락 대기, idle 트랜잭션, 트랜잭션 전체 시간은 각각 lock_timeout, idle_in_transaction_session_timeout, transaction_timeout과 구분해서 보는 편이 정확하다.

참고 자료

• PostgreSQL Documentation: Client Connection Defaults
• PostgreSQL Documentation: SET
• PostgreSQL Documentation: ALTER ROLE
• PostgreSQL Documentation: ALTER DATABASE