depends_on ne suffit pas : healthcheck PostgreSQL dans Compose

depends_on accepte trois conditions :

- service_started (défaut) — attend que le conteneur soit simplement démarré.
- service_healthy — attend que le healthcheck du conteneur renvoie healthy.
- service_completed_successfully — pour les conteneurs à courte durée de vie (jobs, migrations).

Pour toute base de données, service_healthy est la seule condition qui garantit que le service accepte des connexions.

Ajoutez le bloc healthcheck directement dans la définition du service db :

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

Le champ test reçoit une liste : le premier élément est CMD (Docker exécute la commande directement), suivi des arguments. pg_isready renvoie 0 si PostgreSQL est prêt à accepter des connexions sur l'utilisateur et la base indiqués, et un code non nul sinon — ce que Docker interprète comme healthy ou unhealthy.

start_period est la fenêtre de grâce accordée au conteneur pour s'initialiser avant que les échecs de healthcheck ne commencent à être comptabilisés dans retries. Pendant cette fenêtre, Docker lance bien le healthcheck, mais un échec n'incrémente pas le compteur.

Sans start_period, un PostgreSQL qui met 15 secondes à s'initialiser échouerait ses 5 premiers checks (interval: 5s × 5 tentatives = 25 secondes) et passerait en unhealthy avant même d'être opérationnel.

La valeur recommandée est 30 secondes pour un PostgreSQL standard : suffisamment longue pour absorber les initialisations lentes (premier démarrage avec volume vide, extensions lourdes) sans retarder inutilement le démarrage en régime permanent. interval et start_period sont distincts : interval cadence les vérifications en régime normal, start_period protège la phase d'amorçage.

Dans chaque service qui dépend de la base, remplacez la forme courte de depends_on par la forme longue avec condition :

services:
  app:
    image: monapp:latest
    depends_on:
      db:
        condition: service_healthy
    environment:
      DATABASE_URL: postgresql://app:secret@db:5432/appdb

Avec cette configuration, Docker attend que le healthcheck du service db renvoie healthy avant de démarrer app. Si db passe en unhealthy après retries échecs, app ne démarre pas.

Lancez la stack et observez le séquencement :

docker compose up

Vous verrez dans les logs des lignes du type :

db  | database system is ready to accept connections
app | Waiting for db to be healthy...
app | Starting application server

Pour vérifier l'état du healthcheck à tout moment :

docker inspect <nom_du_conteneur_db> | grep -A 5 '"Health"'

La sortie indique Status: healthy, starting ou unhealthy, et liste les dernières sorties du check.

Redis ne dispose pas de redis-isready, mais son équivalent est redis-cli ping :

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 10s

redis-cli ping renvoie PONG et le code de sortie 0 si Redis accepte les connexions. Comme Redis démarre plus vite que PostgreSQL, start_period: 10s est généralement suffisant.

Pour MySQL ou MariaDB, utilisez mysqladmin ping :

  mysql:
    image: mariadb:11
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: appdb
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-psecret"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 30s

Attention : le mot de passe est concaténé directement à -p sans espace (-psecret), c'est le comportement attendu de mysqladmin. Cette commande s'affiche dans docker inspect, donc préférez un secret Compose ou une variable d'environnement si la confidentialité est une contrainte.

pg_isready: command not found — vous n'utilisez pas l'image officielle postgres (ou une image dérivée qui l'inclut). Vérifiez avec docker compose exec db which pg_isready.

Healthcheck en boucle, jamais healthy — le test ne renvoie jamais 0. Testez manuellement : docker compose exec db pg_isready -U app -d appdb. Si la commande échoue, vérifiez les variables d'environnement POSTGRES_USER et POSTGRES_DB.

start_period trop court — sur un premier démarrage avec un volume vide, PostgreSQL peut prendre plus de 30 secondes. Augmentez à 60s ou observez les logs : database system was shut down at … LOG: database system is ready to accept connections indique le délai réel.

Conteneur en unhealthy permanent — après retries échecs, Docker marque le conteneur unhealthy mais ne le redémarre pas (c'est le rôle de restart). Consultez docker inspect pour voir la sortie des derniers checks et identifier la commande qui échoue.