DB 커넥션 풀

DB 커넥션 풀(Connection Pool) 은 데이터베이스 연결을 미리 생성하고 재사용함으로써, 요청마다 새로운 연결을 열고 닫는 오버헤드를 줄이는 패턴이다. 연결 수는 데이터베이스가 허용하는 최대치(max connections)로 제한되므로, 모든 애플리케이션 코드는 반드시 공유 풀을 통해서만 연결을 획득해야 한다. [Engineering — Incidents & Decisions.md]

이 팀에서는 Postgres 를 기본 데이터스토어로 사용하며(ADR-014), 커넥션 풀 관리는 핵심 운영 관심사 중 하나다.

2026-05-12 API 장애 (45분) 는 커넥션 풀을 올바르게 사용하지 않아 발생했다. [Engineering — Incidents & Decisions.md]

• 14:02 배포된 새 엔드포인트가 공유 풀을 사용하지 않고 요청마다 개별 DB 연결을 열었다.
• 부하가 걸리자 14:10에 Postgres 연결이 전부 소진(포화)되었다.
• API 전체가 타임아웃 상태(5xx)에 빠졌고, 결제(checkout)가 차단되었다.
• 14:47 롤백, 14:55 복구 — 총 약 45분간 영향.

1. 1.모든 DB 접근은 공유 풀을 경유한다. 엔드포인트나 백그라운드 작업에서 직접(ad-hoc) 연결을 생성하지 않는다.
2. 2.커넥션은 사용 후 즉시 반납한다. 커넥션을 장시간 점유하면 풀이 조기 소진될 수 있다.
3. 3.풀 사용률을 모니터링한다. 최대 연결 수의 80% 도달 시 알림을 받도록 설정한다(후속 조치 참조).

포스트모텀 에서 도출된 미완료 항목들이다. [Engineering — Incidents & Decisions.md]

• 최대 연결 수의 80% 도달 시 커넥션 수 알림 추가
• 풀 외부에서 임시 연결 생성을 금지하는 린트 규칙 추가
• 릴리스 전 새 엔드포인트 부하 테스트 의무화