--- title: Runbook — DB_IDLE_IN_TX_TIMEOUT (트랜잭션 idle 타임아웃) category: TRANSIENT_DEPENDENCY error_codes: [DB_IDLE_IN_TX_TIMEOUT] severity: P2 owner: oncall last_updated: 2026-11-07 status: 초안 --- # Runbook: DB_IDLE_IN_TX_TIMEOUT (`runbook://db/idle-in-tx-timeout`) ## 증상 - HTTP 503, `error.code=DB_IDLE_IN_TX_TIMEOUT`. - SQLState 25P03. 트랜잭션이 아무 일 없이 너무 오래 열려 있었다. ## 진단 - Postgres의 `idle_in_transaction_session_timeout` 설정을 확인한다. 템플릿은 이 값을 설정하지 않는다. DB나 역할에 걸린 값이다. - 트랜잭션을 오래 쥐고 있는 애플리케이션 코드를 찾는다. 트랜잭션 안에서 외부 호출을 기다리는 코드가 흔한 원인이다. ## 조치 - 애플리케이션 코드에서 트랜잭션 범위를 줄인다. - 트랜잭션 시간 상한(`app.persistence-jpa.transaction.write-timeout`·`read-timeout`)이 정해져 있는지 확인한다. ## 에스컬레이션 - 그 결과로 커넥션 풀이 바닥나면 DBA에 넘긴다. --- > **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.