--- title: Runbook — DB_UNAVAILABLE (데이터베이스 연결 불가) category: TRANSIENT_DEPENDENCY error_codes: [DB_UNAVAILABLE] severity: P1 owner: oncall last_updated: 2026-11-13 status: 초안 --- # Runbook: DB_UNAVAILABLE (`runbook://db/unavailable`) ## 증상 - HTTP 503, `error.code=DB_UNAVAILABLE`. - ERROR 줄 `persistence failure classified as DB_UNAVAILABLE (category=TRANSIENT_DEPENDENCY, retryable=true)`(`ServerFailureLog`). 원인 사슬은 붙지 않아 SQLState·SQL은 로그에 없다. 연결 계열 SQLState(08*)와 PostgreSQL 종료 상태(57P01·57P02)가 이 코드로 분류된다(`PersistenceExceptionTranslator`, `PostgreSqlFailureClassifier`). 쓰기 트랜잭션의 commit 중에 같은 상태가 나면 적용됐는지 모르므로 이 코드가 아니라 `DB_COMPLETION_UNKNOWN`(재시도 금지)이다. ## 진단 - DB 서버 상태와 커넥션 풀 고갈을 확인한다. - 앱 pod에서 DB까지 네트워크가 닿는지 확인한다. ## 조치 - DB primary 상태를 확인한다. replica가 있으면 failover한다. - 커넥션 풀을 비우고 다시 연결한다. ## 에스컬레이션 - P1: DB primary가 내려갔으면 즉시. --- > **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.