depends_on no basta: healthcheck de PostgreSQL en Compose

Por qué `depends_on` falla por defecto

Las consecuencias prácticas de una race condition en el arranque

• connection refused — el socket TCP de PostgreSQL todavía no está abierto y la aplicación falla en la primera llamada PDO o SQLAlchemy.
• FATAL: role does not exist — PostgreSQL escucha, pero los scripts de inicialización (docker-entrypoint-initdb.d) todavía no han creado el rol ni la base de datos.
• FATAL: the database system is starting up — el clúster está recuperándose tras una parada limpia; las conexiones se rechazan temporalmente.
• Crash loop silencioso — con restart: unless-stopped, Docker relanza la aplicación indefinidamente, los logs se repiten y el problema se toma por un error de la aplicación.
• Falsos positivos en CI — las pruebas de integración fallan de forma intermitente según la velocidad de arranque del runner.
• Dependencias en cascada — una API que depende de una aplicación que depende de la base hereda el mismo problema si la cadena depends_on no es correcta de forma uniforme.

Requisitos previos: Docker Compose v2 y el plugin oficial

docker compose version

Configurar un healthcheck de PostgreSQL fiable, paso a paso

1. 01

   Entender service_started frente a service_healthy

   depends_on acepta tres condiciones:

   - service_started (por defecto) — espera a que el contenedor simplemente haya arrancado.
   - service_healthy — espera a que el healthcheck del contenedor devuelva healthy.
   - service_completed_successfully — para contenedores de vida corta (jobs, migraciones).

   Para cualquier base de datos, service_healthy es la única condición que garantiza que el servicio acepta conexiones.

2. 02

   Escribir el healthcheck de PostgreSQL en el servicio `db`

   Añada el bloque healthcheck directamente en la definición del servicio 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

   El campo test recibe una lista: el primer elemento es CMD (Docker ejecuta el comando directamente), seguido de los argumentos. pg_isready devuelve 0 si PostgreSQL está listo para aceptar conexiones con el usuario y la base indicados, y un código distinto de cero en caso contrario — lo que Docker interpreta como healthy o unhealthy.

3. 03

   Entender el papel de `start_period`

   start_period es la ventana de gracia concedida al contenedor para inicializarse antes de que los fallos del healthcheck empiecen a contabilizarse en retries. Durante esa ventana, Docker sí ejecuta el healthcheck, pero un fallo no incrementa el contador.

   Sin start_period, un PostgreSQL que tarda 15 segundos en inicializarse fallaría sus 5 primeras comprobaciones (interval: 5s × 5 intentos = 25 segundos) y pasaría a unhealthy antes incluso de estar operativo.

   El valor recomendado son 30 segundos para un PostgreSQL estándar: lo bastante largo para absorber las inicializaciones lentas (primer arranque con volumen vacío, extensiones pesadas) sin retrasar innecesariamente el arranque en régimen permanente. interval y start_period son distintos: interval marca el ritmo de las comprobaciones en régimen normal, start_period protege la fase de arranque.

4. 04

   Escribir el `depends_on` con `condition: service_healthy`

   En cada servicio que dependa de la base de datos, sustituya la forma corta de depends_on por la forma larga con condición:

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

   Con esta configuración, Docker espera a que el healthcheck del servicio db devuelva healthy antes de arrancar app. Si db pasa a unhealthy tras retries fallos, app no arranca.

5. 05

   Probar con `docker compose up`

   Lance la stack y observe la secuencia:

   docker compose up

   Verá en los logs líneas de este tipo:

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

   Para comprobar el estado del healthcheck en cualquier momento:

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

   La salida indica Status: healthy, starting o unhealthy, y lista las últimas salidas de la comprobación.

6. 06

   Caso Redis: healthcheck adaptado

   Redis no dispone de redis-isready, pero su equivalente es 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 devuelve PONG y el código de salida 0 si Redis acepta conexiones. Como Redis arranca más rápido que PostgreSQL, start_period: 10s suele ser suficiente.

7. 07

   Caso MySQL / MariaDB: `mysqladmin ping`

   Para MySQL o MariaDB, use 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

   Atención: la contraseña se concatena directamente a -p sin espacio (-psecret), es el comportamiento esperado de mysqladmin. Este comando aparece en docker inspect, así que prefiera un secret de Compose o una variable de entorno si la confidencialidad es una restricción.

8. 08

   Resolución de problemas: cuatro errores frecuentes

   pg_isready: command not found — no está usando la imagen oficial postgres (ni una imagen derivada que la incluya). Compruébelo con docker compose exec db which pg_isready.

   Healthcheck en bucle, nunca healthy — el test nunca devuelve 0. Pruébelo manualmente: docker compose exec db pg_isready -U app -d appdb. Si el comando falla, revise las variables de entorno POSTGRES_USER y POSTGRES_DB.

   start_period demasiado corto — en un primer arranque con un volumen vacío, PostgreSQL puede tardar más de 30 segundos. Auméntelo a 60s u observe los logs: database system was shut down at … LOG: database system is ready to accept connections indica el retraso real.

   Contenedor en unhealthy permanente — tras retries fallos, Docker marca el contenedor como unhealthy pero no lo reinicia (eso es tarea de restart). Consulte docker inspect para ver la salida de las últimas comprobaciones e identificar el comando que falla.

Comportamiento por defecto frente a healthcheck

Desplace la tabla

Enlaces internos y próximos pasos