feat(database): PostgreSQL 런타임 연결 타임아웃 보호 추가

[krestar]

왜 필요한가요?

PostgreSQL Runtime Connection에 SQL 실행 시간과 lock 대기 시간을 제한하는 안전선이 없어,
장시간 쿼리나 lock 경합이 Hikari Connection Pool 전체 장애로 확산될 수 있었습니다.

Runtime Connection이 생성될 때 PostgreSQL Session timeout을 적용하고,
확인된 timeout을 안전한 HTTP 응답과 metric으로 분류하기 위한 변경입니다.

• Closes [Reliability] PostgreSQL Runtime Connection 기본 Timeout Guard 도입 #64

무엇이 바뀌나요?

• API·도메인·DB 변경:

  • PostgreSQL Runtime Hikari DataSource를 명시적으로 구성합니다.
  • 새 물리 Connection마다 statement_timeout과 lock_timeout을 Session 범위로 초기화합니다.
  • timeout 설정값의 양수 여부, 정수 millisecond 정밀도, 최대 범위 및 lock < statement 관계를 시작 단계에서 검증합니다.
  • JNDI, Hikari 중복 credential·URL, wrapper JDBC URL, lazy connection 등 초기화 보장을 훼손하는 구성을 시작 단계에서 거부합니다.
  • 확인된 statement/lock timeout은 503 SERVICE_TEMPORARILY_UNAVAILABLE로 응답합니다.
  • SQLState만 일치하거나 canonical diagnostic이 없는 경우 기존 500 INTERNAL_SERVER_ERROR를 유지합니다.
  • DB schema와 Flyway migration은 변경하지 않습니다.

• 권한·Workflow 변경:

  • 권한, Workflow 및 PostgreSQL RLS tenant context 동작은 변경하지 않습니다.
  • Runtime Connection과 Flyway Connection의 credential 및 timeout 적용 경계를 유지합니다.
  • 기존 Outbox retry, backoff, max attempts 및 metric 정책은 변경하지 않습니다.

• AI·외부 연동 변경:

  • 변경 없습니다.

• 문서·배포 변경:

  • DB_STATEMENT_TIMEOUT과 DB_LOCK_TIMEOUT 환경변수 예시를 추가합니다.
  • 지원하는 DataSource 구성, Session 변경 제한, timeout 분류, metric, 배포 확인 및 롤백 절차를 문서화합니다.
  • PostgreSQL lc_messages가 영어가 아닐 때 confirmed timeout이 과소 분류될 수 있는 한계를 명시합니다.

어떻게 검증했나요?

• ./gradlew clean test
• ./gradlew build
• /health와 Swagger UI 확인
• 정상 요청
• 잘못된 입력
• 권한 부족
• 다른 사업장 접근 차단
• 필요한 상태 전이·Idempotency

PostgreSQL 17 Docker 테스트 DB에서 다음 명령을 실행했습니다.

.\gradlew.bat --no-daemon clean test

결과:

215 tests completed
failures: 0
errors: 0
skipped: 0
BUILD SUCCESSFUL

추가로 다음 내용을 단위·Context·PostgreSQL 통합 테스트로 검증했습니다.

• timeout 설정값과 상호 관계 검증
• 충돌하는 DataSource 설정의 fail-fast
• 새 물리 Connection의 Session timeout 적용
• Runtime Connection과 Flyway Connection의 설정 격리
• statement timeout과 lock timeout 발생 및 트랜잭션 rollback
• timeout 이후 Connection Pool의 정상 쿼리 처리
• 잘못된 init SQL을 가진 Connection의 Pool 등록 실패
• confirmed·ambiguous·non-timeout 예외 분류
• 안전한 503 응답, 로그 필드 제한 및 metric 증가

보안·개인정보

• DTO·로그·AI 입력에 불필요한 개인정보가 없습니다.
• JWT, Worker Link 원본 토큰, API Key, 비밀번호가 없습니다.
• 모든 사업장 데이터 접근에 company_id 범위를 검사합니다.
  • 해당 없음: 새로운 데이터 접근 경로나 Repository를 추가하지 않았습니다.
• AI 결과가 자동 승인·발송되지 않습니다.
  • 해당 없음: AI 관련 변경이 없습니다.
• 중요한 변경이 AuditLog와 request_id로 추적됩니다.
  • 상태 변경은 없으며 timeout 로그는 request_id, HTTP method, 안전한 route pattern과 저카디널리티 분류값만 기록합니다.
• 관련 Accepted ADR을 지켰거나 필요한 새 ADR을 이 PR에서 Proposed로 작성했습니다.
  • 기존 PostgreSQL RLS tenant context와 Runtime/Flyway 경계를 유지합니다.
• Server에 Prompt Builder·Provider SDK·모델 routing을 추가하지 않았습니다.

Confirmed 및 ambiguous timeout 로그에는 SQL, bind parameter, PostgreSQL diagnostic 원문, credential, raw URI와 stack trace를 기록하지 않습니다.

API·DB·운영 영향

• Swagger/OpenAPI와 Notion 계약을 갱신했습니다.
  • endpoint 및 응답 DTO schema 변경은 없습니다.
  • 확인된 DB timeout에서 기존 500 대신 공통 오류 형식의 503을 반환합니다.
• Client에 알려야 할 호환성 변경을 적었습니다.
  • 모든 503을 자동 재시도해서는 안 됩니다.
  • GET 등 본질적으로 idempotent한 요청만 제한적으로 재시도합니다.
  • 변경 요청은 동일한 Idempotency-Key가 보장될 때만 재시도해야 합니다.
  • 복구 시점을 보장할 수 없어 Retry-After는 제공하지 않습니다.
• DB 변경에 Flyway migration이 있습니다.
  • 해당 없음: DB schema를 변경하지 않습니다.
• migration 번호와 소유 Issue를 확인했고 다른 기능의 테이블을 미리 만들지 않았습니다.
  • 해당 없음: migration을 추가하지 않았습니다.
• 환경변수는 이름만 .env.example에 적었습니다.
  • DB_STATEMENT_TIMEOUT
  • DB_LOCK_TIMEOUT
• 배포 후 Smoke Test와 롤백 방법을 적었습니다.
  • 전체 애플리케이션 재시작 후 Runtime Connection의 current_setting을 확인합니다.
  • confirmed timeout metric, 정상 쿼리 실행시간, Pool 사용량과 Outbox 지연을 함께 관측합니다.
  • 문제 발생 시 이전 버전을 재배포하고 Runtime Pool 전체를 재생성합니다.

화면 또는 응답 예시

확인된 PostgreSQL Runtime timeout 응답은 기존 공통 오류 형식을 사용합니다.

{
  "timestamp": "2026-07-31T12:00:00Z",
  "status": 503,
  "code": "SERVICE_TEMPORARILY_UNAVAILABLE",
  "message": "일시적으로 요청을 처리할 수 없습니다. 잠시 후 다시 시도해 주세요.",
  "path": "/api/tasks",
  "request_id": "example-request-id",
  "field_errors": []
}

응답과 애플리케이션 로그에는 SQL, PostgreSQL diagnostic 원문, credential 또는 개인정보가 포함되지 않습니다.

리뷰할 부분

• hywznn: 전체 구조와 운영 안정성 측면에서 놓친 위험이나 기존 기능에 미치는 영향이 없는지 확인 부탁드립니다.
• chaeliki: 오류 응답과 트랜잭션 처리 흐름이 자연스러운지 확인 부탁드립니다.