PostgreSQL idle_session_timeout 기준 정리

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

PostgreSQL idle_session_timeout 기준 정리

idle_session_timeout은 PostgreSQL 세션이 트랜잭션을 열지 않은 채 클라이언트 질의를 기다리는 상태로 너무 오래 남아 있을 때 세션을 종료하는 설정이다. 2026년 7월 12일 기준 PostgreSQL 18 공식 문서는 기본값이 0이며, 값을 지정하지 않으면 이 타임아웃이 비활성화된다고 설명한다.

핵심은 이 설정이 "유휴 연결 정리" 용도라는 점이다. 열린 트랜잭션 때문에 락이나 vacuum 지연을 일으키는 상황은 idle_in_transaction_session_timeout이 더 직접적인 대상이고, idle_session_timeout은 그보다 비용이 낮은 일반 유휴 세션을 다룬다. 그래서 어디에나 전역으로 켜기보다, 대화형 접속이나 특정 역할에 한정해 쓰는 편이 더 안전하다.

idle_session_timeout은 정확히 언제 동작할까?

공식 문서 기준 이 타임아웃은 세션이 "client query를 기다리는 idle 상태"이고, 동시에 열린 트랜잭션 안에 있지 않을 때만 적용된다. 즉 BEGIN 이후 멈춰 있는 세션은 이 설정이 아니라 idle_in_transaction_session_timeout의 대상이다.

상태	대상 여부	설명
트랜잭션 없음, 질의 대기 중	적용됨	일반적인 idle 세션 종료 대상
트랜잭션 열림, 질의 대기 중	적용 안 됨	idle_in_transaction_session_timeout이 더 직접적임
쿼리 실행 중	적용 안 됨	실행 시간 제한은 statement_timeout이 담당

이 구분 때문에 "잠깐 놀고 있는 psql 세션을 끊고 싶다"는 요구와 "열린 트랜잭션 때문에 테이블 정리가 밀린다"는 요구는 다른 설정으로 풀어야 한다.

기본값과 단위는 어떻게 볼까?

PostgreSQL 18 문서 기준 기본값은 0이고, 이는 비활성화를 뜻한다. 단위를 생략하면 밀리초로 해석된다. 따라서 600000과 10min은 같은 의미로 볼 수 있지만, 운영 문서와 설정 파일에서는 10min처럼 단위를 함께 적는 편이 읽기 쉽다.

SET idle_session_timeout = '10min';

SET 명령은 현재 세션에만 영향을 준다. PostgreSQL 공식 문서는 세션 안에서 바꾼 런타임 파라미터는 현재 세션에만 적용된다고 설명한다.

전역 기본값으로 두는 편이 맞을까?

공식 문서는 열린 트랜잭션이 없는 idle 세션은 서버에 큰 비용을 주지 않으므로, idle_in_transaction_session_timeout만큼 강하게 이 설정을 켤 필요는 없다고 설명한다. 그래서 모든 세션에 공통 적용되는 postgresql.conf 기본값으로 두기보다, 정말 오래 살아 있으면 곤란한 세션 유형에 좁혀서 적용하는 편이 일반적으로 더 보수적이다.

특히 문서는 연결 풀러나 기타 미들웨어를 거치는 연결에 이 타임아웃을 강제로 적용할 때 주의하라고 경고한다. 예기치 않은 연결 종료를 풀러가 기대하지 않을 수 있기 때문이다.

 

 

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

적용 대상	무난한 판단	이유
운영자가 직접 여는 psql 세션	검토할 만함	잊고 남겨 둔 idle 접속을 정리하기 쉽다
관리용 배스천 계정	검토할 만함	대화형 세션 성격이 강해 유휴 정리 효과가 분명하다
연결 풀러 뒤의 애플리케이션	신중해야 함	공식 문서가 예기치 않은 연결 종료를 주의하라고 설명한다
모든 역할 공통 전역값	대개 보수적으로 접근	idle 세션 자체의 비용이 크지 않기 때문이다

세션별 설정과 역할 기본값은 어떻게 다를까?

현재 접속에만 잠시 적용하려면 SET을 쓰면 된다. 반대로 특정 사용자가 새로 로그인할 때마다 기본값을 적용하고 싶다면 ALTER ROLE ... SET을 사용할 수 있다. PostgreSQL 공식 문서는 역할별 세션 기본값은 새 세션 시작 시점에 적용되며, 이미 열린 세션에는 소급되지 않는다고 설명한다.

ALTER ROLE analyst SET idle_session_timeout = '30min';

이 방식은 모든 사용자에게 전역 적용하지 않고, 대화형 분석 계정이나 운영 계정에만 제한하고 싶을 때 더 잘 맞는다.

다른 timeout과는 어떻게 구분할까?

설정	끊는 기준	주된 목적
statement_timeout	쿼리 실행 시간이 너무 길 때	느린 질의 제한
lock_timeout	락 대기 시간이 너무 길 때	락 대기 제한
idle_in_transaction_session_timeout	트랜잭션을 연 채 idle일 때	락 점유와 vacuum 지연 방지
idle_session_timeout	트랜잭션 없이 idle일 때	일반 유휴 세션 정리

운영 영향도만 놓고 보면 보통은 idle_in_transaction_session_timeout 쪽이 더 긴급하다. idle_session_timeout은 연결 수 관리나 방치된 접속 정리 관점에서 보조적으로 검토하는 편이 맞다.

FAQ

Q. 이 값을 켜면 long-running query도 자동으로 끊기나?

아니다. 공식 문서 기준 이 설정은 idle 상태에만 적용된다. 실행 중인 질의 시간 제한은 statement_timeout이 담당한다.

Q. 열린 트랜잭션을 방치한 세션도 같이 정리되나?

그 경우는 직접 대상이 아니다. 열린 트랜잭션 안에서 idle 상태인 세션은 idle_in_transaction_session_timeout으로 다뤄야 한다.

Q. 풀링 환경이라면 바로 적용해도 될까?

신중해야 한다. PostgreSQL 공식 문서는 connection-pooling software나 middleware가 예기치 않은 연결 종료에 잘 반응하지 않을 수 있다고 경고한다.

정리

idle_session_timeout은 PostgreSQL에서 "트랜잭션을 열지 않은 채 오래 놀고 있는 세션"을 정리하는 설정이다. 2026년 7월 12일 기준 PostgreSQL 18 공식 문서만 보면 기본값은 비활성화이고, 모든 세션에 전역 강제하기보다 대화형 세션이나 특정 역할에 선택적으로 적용하는 쪽이 더 무난하다.

판단 기준은 세 가지로 압축할 수 있다. 첫째, 문제가 되는 세션이 정말 일반 idle인지, 아니면 열린 트랜잭션 idle인지 구분한다. 둘째, 풀러나 미들웨어가 예기치 않은 세션 종료를 안전하게 처리할 수 있는지 본다. 셋째, 전역 설정보다 SET이나 ALTER ROLE ... SET으로 범위를 좁힐 수 있는지 먼저 검토한다.

참고 자료

• PostgreSQL 18 공식 문서: Client Connection Defaults
• PostgreSQL 18 공식 문서: SET
• PostgreSQL 18 공식 문서: ALTER ROLE