Docker Composeのdepends_onとHEALTHCHECK｜サービス起動順序を確実に制御する設計パターン

この記事のポイント

・depends_on の condition: service_healthy でDBの準備完了を待ってからアプリを起動できる
・HEALTHCHECK 命令でコンテナの「準備完了」基準を定義する（Dockerfile / Composeファイル）
・docker inspect コマンドでヘルスチェック状態とログを確認してデバッグできる
・起動順序制御だけでなくアプリ側の接続リトライ実装が運用上の鉄則

app_1  | sqlalchemy.exc.OperationalError: (psycopg2.OperationalError)
app_1  | could not connect to server: Connection refused
app_1  |     Is the server running on host "db" (172.18.0.2) and accepting
app_1  |     TCP/IP connections on port 5432?

# condition を省略した例（service_started と同義）
services:
  app:
    image: myapp:latest
    depends_on:
      - db       # プロセス起動のみ確認。DB準備完了は保証しない
  db:
    image: postgres:16

services:
  app:
    image: myapp:latest
    depends_on:
      db:
        condition: service_healthy   # dbがhealthyになるまで起動しない
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

services:
  app:
    image: myapp:latest
    depends_on:
      migrate:
        condition: service_completed_successfully  # マイグレーション完了後に起動
  migrate:
    image: myapp:latest
    command: python manage.py migrate
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

# PostgreSQLイメージに対するHEALTHCHECKの例
FROM postgres:16

# pg_isready でDBが接続を受け付けているか確認
HEALTHCHECK --interval=5s --timeout=5s --start-period=10s --retries=5   CMD pg_isready -U postgres || exit 1

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
      interval: 5s
      timeout: 5s
      start_period: 10s
      retries: 5

# docker-compose.yml
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
      interval: 5s
      timeout: 5s
      start_period: 10s
      retries: 5
    volumes:
      - pgdata:/var/lib/postgresql/data

  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: "postgresql://appuser:secret@db:5432/appdb"
    depends_on:
      db:
        condition: service_healthy   # dbがhealthyになってから起動
    restart: on-failure              # 接続失敗時にリスタート

volumes:
  pgdata:

$ docker compose up -d
[+] Running 2/2
 ✔ Container sample-db-1   Healthy    6.5s
 ✔ Container sample-app-1  Started    6.8s

$ docker compose ps
NAME             IMAGE          STATUS                   PORTS
sample-app-1     myapp:latest   Up 10 seconds            0.0.0.0:8000->8000/tcp
sample-db-1      postgres:16    Up 15 seconds (healthy)  5432/tcp

# コンテナ名を確認
$ docker compose ps

# ヘルスチェック詳細を取得
$ docker inspect sample-db-1 | python3 -m json.tool | grep -A 20 '"Health"'

# 出力例（失敗している場合）
"Health": {
    "Status": "unhealthy",
    "FailingStreak": 3,
    "Log": [
        {
            "Start": "2026-07-07T08:00:01.234Z",
            "End":   "2026-07-07T08:00:01.239Z",
            "ExitCode": 1,
            "Output": "pg_isready: error: connection to server at "localhost" failed"
        }
    ]
}

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
  interval: 10s
  timeout: 5s
  start_period: 15s
  retries: 3

# SQLAlchemy の接続リトライ設定例
from sqlalchemy import create_engine

engine = create_engine(
    "postgresql://appuser:secret@db:5432/appdb",
    pool_pre_ping=True,         # 使用前に接続確認
    pool_recycle=3600,          # 1時間で接続を再作成
    connect_args={"connect_timeout": 10}
)