Docker Compose에서 depends_on만으로는 DB 대기가 불가능: healthcheck와 service_healthy 활용법

요약

이 글은 Docker Compose 환경에서 API와 DB 간의 연결 문제를 다루며, 단순히 `depends_on`만으로는 컨테이너가 실행되는 것과 DB가 실제로 접속 가능한 상태(ready)를 구분할 수 없음을 분석합니다. 따라서 안정적인 배포를 위해 `healthcheck` 기능을 활용하고, 이를 `condition: service_healthy`와 결합하여 사용하는 방법을 제시합니다.

핵심 포인트

• `depends_on`은 컨테이너의 시작 순서만 지정하며, DB가 실제로 연결을 받을 준비가 되었음을 보장하지 않습니다.
• DB가 정상적으로 작동하는지 확인하려면 `healthcheck`를 설정하여 주기적인 상태 검사를 수행해야 합니다.
• 안정적인 서비스 구동을 위해서는 `depends_on`에 `condition: service_healthy`를 사용하여 DB의 건강 상태를 기다리는 것이 필수적입니다.
• '시작 시 대기 로직'과 '운영 중 장애 발생 시 복구(재연결) 로직'은 분리하여 설계해야 합니다.