docker compose healthcheck｜depends_onの待ち方

depends_on を短い書き方（- db）にすると、Compose は db のコンテナが「動き始めた」ところで次を起動します。DB が接続を受け付けるまで待たせるには、db に healthcheck を書き、待つ側に condition: service_healthy を書きます。

services:
  db:
    image: postgres:18
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?}
      POSTGRES_DB: appdb
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 60s
      start_interval: 1s

  app:
    build: .
    depends_on:
      db:
        condition: service_healthy   # db が healthy になるまで app を起動しない

この記事で手元で確かめたことです。

確認環境：compose ファイルは、Docker Compose v5.6.0 が使っている compose-go v2.16.1 を Go 1.24.7 で組み込んだ小さなプログラムで読み込み、正規化された結果とエラー文を確かめました。待ち合わせの動きは docker/compose v5.6.0 のソース（pkg/compose/service_containers.go）、healthcheck の既定値とタイミングは moby（Docker Engine）のソース（daemon/health.go）、仕様は compose-spec の原文と Docker のドキュメントで確かめています。ヘルスチェックのコマンドは Ubuntu 24.04 の apt で入れた PostgreSQL 16.15（pg_isready 16.15）、MySQL 8.0.46、Valkey 7.2.13（valkey-cli 7.2.4）を起動・停止して、成功・失敗時の終了コードを確かめました（確認日 2026年10月13日）。

depends_on だけでは「準備完了」を待たない

Docker のドキュメントには「On startup, Compose does not wait until a container is "ready", only until it's running.」とあります。PostgreSQL や MySQL は、プロセスが動き始めてから接続を受け付けるまでに時間がかかります。その間にアプリが接続すると、Connection refused などで落ちます。

sequenceDiagram
    participant C as docker compose up
    participant DB as db コンテナ
    participant A as app コンテナ
    C->>DB: 起動
    Note over DB: starting（ヘルスチェック待ち）
    DB-->>C: healthcheck 成功 → healthy
    C->>A: 起動（service_healthy を満たした）

Compose のソース（v5.6.0）では、待つ側のサービスを起動する前に、依存先のコンテナの状態を 0.5秒ごとに調べています。条件ごとの動きは次の通りです。

service_healthy の依存先が先に終了すると、終了コードが 0 でも失敗になります。 終わるコマンド（マイグレーション・初期データ投入）を待つときは service_completed_successfully を使います。

短い書き方と長い書き方

services:
  app:
    depends_on:        # 短い書き方：起動順だけ
      - db
      - cache

services:
  app:
    depends_on:        # 長い書き方：条件・再起動・必須を指定できる
      db:
        condition: service_healthy
        restart: true
      cache:
        condition: service_started
        required: false

compose-go で短い書き方を読み込むと、condition: service_started と required: true が補われました。

restart は Compose v2.17.0、required は v2.20.0 で入ったと compose-spec に書かれています。

required: false を使う場面

profiles で起動しないことがあるサービスに依存するときに使います。 compose-go で確かめた結果です。

services:
  app:
    image: myapp
    depends_on:
      worker:
        condition: service_started
  worker:
    image: myapp
    profiles: ["worker"]   # --profile worker のときだけ起動

service "app" depends on undefined service "worker": invalid compose project

required: false を付けると、このエラーにならずに読み込めました。

healthcheck の項目と既定値

既定値は Docker Engine のソース（defaultProbeInterval = 30 * time.Second など）と Dockerfile リファレンスで同じ値でした。compose-spec には「It works in the same way, and has the same default values, as the HEALTHCHECK Dockerfile instruction」とあり、Compose で書かなかった項目はこの値になります。

時間は 10s・1m30s・500ms のように単位付きの文字列で書きます。interval: 10 と数字だけにすると、compose-go では次のエラーになりました。

validating compose.yaml: services.db.healthcheck.interval must be a string

1回目のチェックはいつ動くか

Engine のソースでは、start_period の間（状態が starting のとき）は start_interval で、それ以外は interval で次のチェックまで待ちます。既定のままだと、1回目のチェックは起動の 30秒後です。 service_healthy で待つ側も、少なくとも 30秒待たされます。

start_interval は start_period が 0 だと使われません。 起動を早く検知したいときは、2つを組み合わせます。

healthy・unhealthy の決まり方

Dockerfile リファレンスには「if a health check succeeds during the start period, the container is considered started and all consecutive failures will be counted」とあります。1回成功した後は、start_period の間でも失敗を数えます。

終了コードは 0 が成功、それ以外はすべて失敗です。 リファレンスでは 1 を unhealthy、2 を予約済みとしていますが、Engine のソースでは 0 以外をまとめて失敗として扱っています。curl -f が返す 22 や 7 も失敗になります。|| exit 1 は、リファレンスの決まりに合わせて 1 にそろえる書き方です。

test の書き方

リストの1つ目が CMD・CMD-SHELL・NONE 以外だとエラーになります。 ["pg_isready"] と書くと compose-go では次のエラーでした。

healthcheck.test must start either by "CMD", "CMD-SHELL" or "NONE"

DB ごとのヘルスチェックのコマンド

apt の PostgreSQL 16.15・MySQL 8.0.46・Valkey 7.2.13 を起動・停止して、各コマンドの終了コードを確かめました。

PostgreSQL：pg_isready

pg_isready はサーバーが接続を受け付けるかだけを見ます。 -U と -d を誤っても成功になりました。ユーザー・パスワード・DB まで確かめたいときは psql で SELECT 1 を実行します。

    healthcheck:
      # 接続を受け付けるか（軽い）
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]

    healthcheck:
      # ログインして SQL が通るか（認証と DB の有無まで確かめる）
      test: ["CMD-SHELL", "PGPASSWORD=$${POSTGRES_PASSWORD} psql -h 127.0.0.1 -U $${POSTGRES_USER} -d $${POSTGRES_DB} -tAc 'SELECT 1'"]

-h 127.0.0.1 を付けて TCP で確かめます。 公式 postgres イメージの docker-entrypoint.sh は、初回（データが空のとき）に初期化用の一時サーバーを listen_addresses=''（TCP を開かない）で起動し、初期化が終わると止めて本番のサーバーを起動し直します。-h を付けないとソケットで一時サーバーに接続でき、初期化の途中で healthy になることがあります。

postgres:18 から、イメージの VOLUME は /var/lib/postgresql/data から /var/lib/postgresql に変わっています（イメージの Dockerfile のコメントより）。

MySQL：mysqladmin ping より mysql で SELECT 1

mysqladmin ping は、サーバーが応答すればパスワードを誤っても 0 を返しました。 MySQL のマニュアルにも、ping の戻り値は「Access denied」のようなエラーでも 0 になると書かれています。 「サーバーが動いているか」の確認には使えますが、アプリのユーザーで接続できるかまでは分かりません。

services:
  mysql:
    image: mysql:8.4
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:?}
      MYSQL_DATABASE: appdb
      MYSQL_USER: app
      MYSQL_PASSWORD: ${MYSQL_PASSWORD:?}
    volumes:
      - mysqldata:/var/lib/mysql
    healthcheck:
      test: ["CMD-SHELL", "mysql -h 127.0.0.1 -u\"$${MYSQL_USER}\" -p\"$${MYSQL_PASSWORD}\" -e 'SELECT 1' \"$${MYSQL_DATABASE}\""]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 90s
      start_interval: 2s
volumes:
  mysqldata:

ここでも -h 127.0.0.1 を付けます。 公式 mysql イメージの docker-entrypoint.sh も、初期化用の一時サーバーを --skip-networking（TCP を開かない）で起動します。-h を省くと localhost 扱いでソケットに接続し、一時サーバーに対して成功することがあります。-p でパスワードを渡すと Using a password on the command line interface can be insecure. の警告が出ますが、終了コードには影響しませんでした。

Redis・Valkey：PONG を grep で確かめる

valkey-cli はエラーの応答でも 0 を返しました。 PONG が返ったかを grep -q PONG で確かめると、認証の誤りも失敗として扱えます。パスワードは -a より環境変数 REDISCLI_AUTH で渡すと、Warning: Using a password with '-a' or '-u' option on the command line interface may not be safe. の警告も出ません。

services:
  cache:
    image: valkey/valkey:8
    command: ["valkey-server", "--requirepass", "${VALKEY_PASSWORD:?}"]
    environment:
      REDISCLI_AUTH: ${VALKEY_PASSWORD:?}
    healthcheck:
      test: ["CMD-SHELL", "valkey-cli ping | grep -q PONG"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 10s
      start_interval: 1s

redis イメージでは、valkey-cli を redis-cli に置き換えます。Valkey と Redis の作り方と接続コードは、関連記事「ElastiCacheの使い方｜Valkey/Redisの作り方と接続コード」で扱っています。

Web アプリ：curl が無いイメージ

イメージに curl が入っているとは限りません。 公式 postgres イメージの Dockerfile は、gosu の取得に使った wget を最後に削除し、curl は入れていません。node や python のイメージでは、その言語でリクエストを送る書き方が使えます。手元で、200 と 503 を返す小さなサーバーに対して確かめた結果です。

curl は -f を付けないと 503 でも 0 を返します。 alpine 系のイメージには BusyBox の wget が入っていることが多く、distroless のようにシェルも無いイメージでは、アプリ自身にヘルスチェック用のサブコマンドを持たせて CMD 形式で呼ぶ方法があります。

    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]

/health で何を返すか（DB まで見るか）の設計は、関連記事「ヘルスチェック設計｜livenessとreadinessの違いと実装例」で扱っています。

コピペ用：DB・キャッシュ・マイグレーション・アプリ

PostgreSQL と Valkey が healthy になり、マイグレーションが終了コード 0 で終わってからアプリを起動する構成です。compose-go v2.16.1 でエラーなく読み込めることを確かめています。

services:
  db:
    image: postgres:18
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD を .env に書く}
      POSTGRES_DB: appdb
    volumes:
      - pgdata:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 60s
      start_interval: 1s

  cache:
    image: valkey/valkey:8
    command: ["valkey-server", "--requirepass", "${VALKEY_PASSWORD:?}"]
    environment:
      REDISCLI_AUTH: ${VALKEY_PASSWORD:?}
    healthcheck:
      test: ["CMD-SHELL", "valkey-cli ping | grep -q PONG"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 10s
      start_interval: 1s

  migrate:
    build: .
    command: ["npm", "run", "migrate"]
    environment:
      DATABASE_URL: postgres://app:${POSTGRES_PASSWORD}@db:5432/appdb
    depends_on:
      db:
        condition: service_healthy

  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://app:${POSTGRES_PASSWORD}@db:5432/appdb
      REDIS_URL: redis://:${VALKEY_PASSWORD}@cache:6379
    depends_on:
      db:
        condition: service_healthy
        restart: true
      cache:
        condition: service_healthy
      migrate:
        condition: service_completed_successfully
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s
      start_interval: 2s
    restart: unless-stopped

volumes:
  pgdata:

# .env（Git に入れない）
POSTGRES_PASSWORD=change-me
VALKEY_PASSWORD=change-me

.env が無いときは、${VAR:?} の書き方により次のエラーで止まりました。空のパスワードで起動するのを防げます。

error while interpolating services.db.environment.POSTGRES_PASSWORD: required variable POSTGRES_PASSWORD is missing a value: POSTGRES_PASSWORD を .env に書く

起動と確かめ方

docker compose up -d --wait --wait-timeout 120   # healthy になるまで待って戻る（CI 向け）
docker compose ps                                 # STATUS に (healthy) / (unhealthy) / (health: starting)
docker inspect --format '{{json .State.Health}}' <コンテナ名>   # 直近のチェック結果と出力
docker compose config                             # 変数を展開した結果を見る

--wait-timeout を付けないと、依存先が starting のままなら待ち続けます。 CI では時間の上限を付けておくと、止まったまま時間を使い切ることを防げます。docker inspect で見える出力は、Dockerfile リファレンスによると先頭の 4096 バイトまでで、記録は直近の5回分です（Engine のソースの maxLogEntries = 5）。

restart（再起動ポリシー）との関係

unhealthy になっても、コンテナは止まらず、再起動もされません。 Engine のソースでは、ヘルスチェックの結果は状態を書き換えてイベントを出すだけです。compose-spec の restart も「the policy that the platform applies on container termination」と、終了時の動きとして書かれています。unhealthy で入れ替えたいときは、オーケストレーター（Kubernetes の livenessProbe など）を使うか、アプリが自分で終了するようにします。

よくある誤り

$ のエスケープの違いを、compose-go で読み込んで確かめた結果です（.env に POSTGRES_USER=app）。

$${...} は、コンテナの environment に設定した値を使います。 .env の値で置き換わる $ だけの書き方も動きますが、.env とコンテナの環境変数がずれると、チェックだけが別のユーザーで動きます。

compose.yaml の基本の書き方は関連記事「Docker Composeの使い方｜compose.yamlの書き方と開発環境の作り方」、ネットワークとボリュームは「Docker network/volume使い方｜種類比較表と実行ログで理解」で扱っています。イメージ側に HEALTHCHECK を書く場合の Dockerfile の書き方は、関連記事「Dockerfileの書き方｜軽く・速く・安全なイメージを作るベストプラクティス」で扱っています。

よくある質問

Q. wait-for-it.sh や dockerize は要りますか？ A. Compose の service_healthy で、多くの「DB を待つ」用途は書けます。ただし Compose が待つのは、Compose がサービスを起動するときです。DB が途中で再起動したときのために、アプリ側にも再接続の処理（リトライと待ち時間）を入れておくと、起動順に頼らずに済みます。

Q. version: "3.8" は書く必要がありますか？ A. compose-spec では version は互換のためだけに残っている項目で、Compose は値を使いません。compose-go で version: "3.8" を読み込むと、次の警告が出ました。書かなくても、この記事の condition や start_interval は使えます。

the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion

Q. Dockerfile の HEALTHCHECK と compose の healthcheck の両方を書いたら？ A. compose-spec には「Your Compose file can override the values set in the Dockerfile.」とあり、compose の値が使われます。イメージの healthcheck を止めたいときは disable: true を書きます。

Q. GitHub Actions のサービスコンテナでも同じ書き方ですか？ A. GitHub Actions の services: では、options: --health-cmd "pg_isready" --health-interval 10s ... のように docker run のオプションで書きます。項目の意味と既定値はこの記事の表と同じです。

まとめ

• 短い depends_on は起動順だけ。準備完了を待つには、依存先に healthcheck、待つ側に condition: service_healthy
• マイグレーションなど終わるものは service_completed_successfully（service_healthy だと終了で失敗になる）
• 既定値は interval 30s・timeout 30s・retries 3・start_period 0s・start_interval 5s。1回目も 30秒後なので、start_period と start_interval で早める
• pg_isready・mysqladmin ping・valkey-cli ping は認証の誤りでも 0 を返した。SELECT 1 や grep -q PONG で確かめる
• 公式イメージの初期化用一時サーバーを避けるため、-h 127.0.0.1 で TCP 接続して確かめる
• コンテナ内の変数は $$ でエスケープし、CMD-SHELL で書く
• unhealthy になっても再起動はされない。CI では up --wait --wait-timeout

参考・出典

確認日はいずれも 2026年10月13日です。

• Docker Docs「Control startup and shutdown order in Compose」：https://docs.docker.com/compose/how-tos/startup-order/
• Docker Docs「Dockerfile reference - HEALTHCHECK」：https://docs.docker.com/reference/dockerfile/#healthcheck
• Docker Docs「docker compose up」：https://docs.docker.com/reference/cli/docker/compose/up/
• compose-spec「Services top-level elements」（05-services.md）：https://github.com/compose-spec/compose-spec/blob/main/05-services.md
• compose-spec/compose-go v2.16.1：https://github.com/compose-spec/compose-go
• docker/compose v5.6.0（pkg/compose/service_containers.go）：https://github.com/docker/compose
• moby/moby（daemon/health.go）：https://github.com/moby/moby/blob/master/daemon/health.go
• docker-library/postgres（docker-entrypoint.sh・Dockerfile）：https://github.com/docker-library/postgres
• docker-library/mysql（docker-entrypoint.sh）：https://github.com/docker-library/mysql
• PostgreSQL Documentation「pg_isready」：https://www.postgresql.org/docs/16/app-pg-isready.html
• MySQL 8.0 Reference Manual「mysqladmin」：https://dev.mysql.com/doc/refman/8.0/en/mysqladmin.html

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。