Docker Compose에서 DB 준비 전에 앱이 시작될 때: depends_on과 healthcheck

Docker Compose에서 앱이 시작 직후 데이터베이스 연결에 실패한다면, 컨테이너가 실행 중인 것과 데이터베이스가 연결을 받을 준비가 된 것을 구분해야 한다. 기본 depends_on은 시작 순서를 정하지만 준비 완료까지 기다리지 않는다. 의존 서비스에 적절한 healthcheck를 두고 condition: service_healthy를 사용하면 초기 시작 시 검사 통과를 기다릴 수 있다. 이후 장애에 대비한 재연결 처리는 앱에 별도로 필요하다.

서비스 준비를 기다리는 시작 순서를 표현한 생성형 개념 이미지다. 실제 Docker 화면은 아니다.

문서 확인: 2026-11-03. 아래 구성은 공식 문서를 바탕으로 작성한 설명용 예제다. 이 환경에는 Docker가 없어 실행하거나 장애를 재현하지 않았다.

실행 중과 준비 완료는 다르다

Compose는 의존성 순서로 서비스를 만들고 시작한다. 그러나 짧은 형식인 depends_on: [db]는 데이터베이스가 초기화와 연결 수락을 마쳤는지 확인하지 않는다. 앱이 먼저 연결을 시도하면 시작 타이밍에 따라 실패할 수 있다. Docker 시작 순서 문서

긴 형식에서 service_started는 시작을, service_healthy는 해당 서비스의 상태 검사 통과를 기다린다. service_completed_successfully는 일회성 작업이 성공 종료한 뒤 다음 서비스를 시작할 때 쓸 수 있다. Compose 서비스 참조

PostgreSQL 준비를 기다리는 예제

다음은 실제 애플리케이션 대신 PostgreSQL 클라이언트로 연결을 한 번 시도하는 최소 예제다. 빈 작업 디렉터리에 compose.yaml로 저장한다. 암호는 로컬 실습용이며 운영 환경에 그대로 쓰면 안 된다.

pg_isready는 서버가 연결을 수락할 준비가 됐는지 검사한다. 이것만으로 앱이 사용하는 계정의 권한, 필요한 테이블이나 마이그레이션 완료를 보증하지 않는다. 이미지 안에서 검사 명령이 존재해야 하며, 실제 서비스에서는 필요한 준비 조건에 맞게 검사를 설계한다. PostgreSQL pg_isready

interval, timeout, retries, start_period는 검사 간격, 실행 시간 제한, 실패 허용과 초기화 유예를 조절한다. 이 값들은 예제이며 실제 시작 시간과 장애 감지 목표에 맞춰 조정한다. 검사 통과 전에는 의존 앱이 시작되지 않으며, 상태 검사가 실패 상태로 끝나면 시작이 막힐 수 있다. Docker healthcheck 참조

구성과 상태를 확인한다

아래 명령은 독립된 로컬 실습 프로젝트에서 실행한다. 이미지를 가져오므로 네트워크와 Docker Engine이 필요하다.

config는 Compose가 해석한 설정을 확인하는 단계다. 출력에 환경변수나 비밀값이 포함될 수 있으므로 공유 전 확인한다. up에서는 db가 healthy가 된 뒤 일회성 app이 SELECT 1을 수행하고 종료하는지 확인한다. 실제 출력은 환경에 따라 다르며, 여기서 실행했다고 주장하지 않는다.

별도 터미널에서 docker compose ps -a로 컨테이너와 health 상태를 확인하고, docker compose logs db app에서 검사 실패와 앱 연결 오류를 구분한다. 일회성 app이 정상 종료해도 계속 실행 중인 웹 서버를 시험한 것은 아니다. 실습을 마치면 해당 디렉터리에서 docker compose down으로 프로젝트를 정리한다. 기존 프로젝트나 데이터를 대상으로 실행하지 않는다. Compose CLI

시작 이후 장애는 별도로 처리한다

service_healthy는 초기 의존성 시작을 조정한다. 데이터베이스가 나중에 재시작되거나 네트워크가 끊겼을 때 앱이 자동으로 연결을 복구한다는 보장은 아니다. 앱에서는 연결 시간 제한, 제한된 재시도와 백오프, 재연결 및 실패 관측을 별도로 설계한다. 비멱등 작업의 무분별한 재시도도 피해야 한다.

또한 depends_on의 긴 형식에 있는 restart: true는 Compose가 의존 서비스를 명시적으로 업데이트·재시작하는 경우의 연동 옵션이다. 컨테이너 런타임이 장애로 자동 재시작하는 모든 경우를 감시하는 기능이나 앱의 재연결 로직과 동일하지 않다. 공식 참조

검사 대상은 “프로세스가 존재하는가”보다 앱에 필요한 조건에 가깝게 정하되, 준비 검사 하나가 운영 중 모든 오류를 증명한다고 가정하지 않는다. 마이그레이션은 별도 일회성 서비스와 성공 종료 조건으로 모델링하고, 실제 앱 계정으로 필요한 스키마와 권한을 확인하는 검증을 추가할 수 있다. 이 글은 해당 마이그레이션이나 장애 복구를 실행 검증하지 않았다.

English version: Docker Compose Startup Order: Wait for Database Readiness with healthcheck