Docker Composeサービス依存関係：ヘルスチェック設定でデータベース起動順序問題を解決する

「データベースに接続できません。Connection refused。」

Docker Composeを使ってアプリケーションを開発しているとき、このエラーに遭遇したことはありませんか？
「あれ？depends_onでデータベースを指定したはずなのに、なんで？」と思ったことでしょう。

そして多くの人が、wait-for-it.shのようなシェルスクリプトを探してきて、コンテナ起動時にデータベースのポートが開くのを待つようなハックをしてしまいます。

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

しかし、2025年の今、もっとエレガントでDockerネイティブな解決策があります。外部スクリプトはもう不要です。今日は、Docker Composeのhealthcheck機能を使って、この問題を根本から解決する方法を解説します。

なぜdepends_onだけでは不十分なのか？

ドキュメントをよく読むと、衝撃的な事実が書いてあります。

depends_on expresses start order, not readiness.

つまり、depends_onは「起動順序」を保証するだけで、「準備完了」までは待ってくれないのです。

よくある失敗シナリオ

1. Dockerがデータベースコンテナ（PostgreSQLなど）を起動します。
2. PostgreSQLのプロセスが立ち上がります。この時点でDockerは「起動完了」と判断します。
3. Dockerが依存するWebアプリコンテナを起動します。
4. Webアプリが即座にデータベースに接続しようとします。
5. しかし、PostgreSQLはまだ初期化処理（データディレクトリの作成、configの読み込みなど）を行っており、ポート35432はまだリクエストを受け付けていません。
6. Webアプリがクラッシュします。「Connection refused」。

プロセスが起動していることと、サービスがリクエストを受け付けられる状態であることは、全く別物なのです。

正解：Healthcheck + Condition

この問題を解決するには、Dockerに「コンテナが起動したか」ではなく、「サービスが健全（Healthy）か」を判断させる必要があります。

これには2つのステップが必要です：

1. データベースコンテナにhealthcheck（健康診断）を定義する。
2. Webアプリコンテナのdepends_onで、condition: service_healthyを指定する。

実践：PostgreSQLの場合

PostgreSQLにはpg_isreadyという便利なユーティリティが含まれています。これを使います。

Alibaba Cloud - 開発者向けクラウドの第一候補、ライトサーバー15%OFF、プロジェクトの迅速な立ち上げを支援

15%割引を入手 →広告

version: '3.8'

services:
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mydb
    # ステップ1：ヘルスチェックを定義
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d mydb"]
      interval: 5s       # 5秒ごとにチェック
      timeout: 5s        # タイムアウト5秒
      retries: 5         # 5回失敗したらUnhealthyとみなす
      start_period: 10s  # 起動直後の10秒間は失敗してもカウントしない
    ports:
      - "5432:5432"

  app:
    build: .
    # ステップ2：Healthyになるまで待つ
    depends_on:
      db:
        condition: service_healthy
    environment:
      DATABASE_URL: postgres://user:password@db:5432/mydb

これで、Webアプリはpg_isreadyコマンドが成功（exit code 0）を返すまで、つまりデータベースが本当に接続を受け付けられるようになるまで、起動を待機します。

実践：MySQLの場合

MySQLの場合はmysqladmin pingを使います。

version: '3.8'

services:
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: mydb
      MYSQL_USER: user
      MYSQL_PASSWORD: password
    # ステップ1：ヘルスチェックを定義
    healthcheck:
      test: ["CMD-SHELL", "mysqladmin ping -h localhost -u root -p$$MYSQL_ROOT_PASSWORD"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 30s # SQLiteなどと違い、MySQLの初期化は重いので長めに
    ports:
      - "3306:3306"

  app:
    build: .
    # ステップ2：Healthyになるまで待つ
    depends_on:
      db:
        condition: service_healthy
    environment:
      DATABASE_URL: mysql://user:password@db:3306/mydb

注意点：docker-compose.yml内で環境変数を使用する場合、$は$$とエスケープする必要があります（例：-p$$MYSQL_ROOT_PASSWORD）。

Railway - モダンなデプロイプラットフォーム、煩わしい運用から解放、数分で公開

今すぐ始める →広告

その他のサービス（Redis, Elasticsearchなど）

Redis:

healthcheck:
  test: ["CMD", "redis-cli", "ping"]
  interval: 5s
  timeout: 3s
  retries: 3

Elasticsearch:

healthcheck:
  test: ["CMD-SHELL", "curl -s http://localhost:9200 >/dev/null || exit 1"]
  interval: 10s
  timeout: 10s
  retries: 5

基本的に、「そのサービスが応答するかどうか」を確認するコマンドがあれば何でもOKです。curl、wget、専用CLIツールなどが使えます。

start_periodの重要性

healthcheckの設定の中にstart_periodという項目がありましたね。これは非常に重要です。

データベースの初回起動時は、初期データの投入などが行われるため、通常より起動に時間がかかります。この期間中にヘルスチェックが失敗しても、それは「異常」ではなく「準備中」です。

start_periodを設定しないと、初期化中にretries回数を超えて失敗してしまい、Dockerが「このコンテナは壊れている」と判断して再起動を繰り返す（Restart Loop）可能性があります。

• PostgreSQL: 10秒〜30秒あれば十分
• MySQL/MariaDB: 初回は重いので30秒〜60秒推奨

結論

wait-for-it.shやsleep 10のようなハックはもう卒業しましょう。Docker Compose標準の機能だけで、堅牢な依存関係管理が可能です。

1. データストア側のコンテナにhealthcheckを書く。
2. アプリ側のdepends_onにcondition: service_healthyを書く。

たったこれだけで、“Connection refused”による起動失敗は過去のものになります。今日のコミットで、あなたのdocker-compose.ymlをアップデートしてみませんか？

2 min read · 公開日: 2025年12月17日 · 更新日: 2026年1月22日

Easton

技術開発