Uno de los problemas más frustrantes al trabajar con Docker Compose aparece cuando arrancas un proyecto y la aplicación intenta conectarse a la base de datos antes de que esta esté preparada. ¿Te encuentras en medio de este lío? Vamos a explicarte qué hacer cuando Docker Compose arranca la aplicación antes que la base de datos: la solución es más sencilla de lo que parece.
Por qué Docker Compose arranca la aplicación antes que la base de datos
Comencemos por entender por qué Docker Compose arranca la aplicación antes que la base de datos. En un proyecto habitual, la aplicación web necesita conectarse a una base de datos como MySQL, PostgreSQL o MariaDB. Lo normal es que ambos servicios se ejecuten en contenedores independientes y se coordinen mediante un archivo compose.yaml o docker-compose.yml.
Pero el problema aparece durante el arranque. Docker Compose puede iniciar primero el contenedor de la base de datos y después el de la aplicación (depends_on). Sin embargo, eso no garantiza que el motor de la base de datos haya terminado de inicializarse. Por ejemplo, MySQL puede necesitar unos segundos para preparar sus archivos internos, crear las tablas del sistema, aplicar configuraciones y habilitar las conexiones.
Mientras tanto, la aplicación ya se está ejecutando e intenta acceder al servidor. Pero, como este todavía no está listo para recibir conexiones, la aplicación registra errores como connection refused, could not connect to server o database unavailable. Igual pasa si ocurre una interrupción o reinicias los contenedores: la aplicación puede volver a intentar conectarse demasiado pronto.
Aquí hay que distinguir dos conceptos diferentes: el orden de inicio de los contenedores y la disponibilidad real de los servicios. Mientras que el servidor se pone a tono, la aplicación arranca al instante e intenta conectarse. Pero, si no tiene lógica de reintento, termina muriendo y solo revive en un segundo intento manual de conexión (docker compose restart app). Claro: en el segundo intento la base de datos lleva tiempo corriendo y está lista.
Docker Compose arranca la aplicación antes que la base de datos: cómo evitar el fallo
Resumiendo, Compose inicia los contenedores en el orden dictado por depends_on, pero no espera a que el contenedor esté listo, sólo a que esté ejecutándose. La forma corta de depends_on (la lista simple de servicios) solo garantiza el orden de la creación, no la disponibilidad del servicio dependiente. ¿Solución? Para sincronizar de verdad, hay que usar la forma larga con condition y, del lado de la base de datos, un healthcheck que defina qué significa “estar sano”.
Lo que oficialmente se recomienda hacer cuando Docker Compose arranca la aplicación antes que la base de datos requiere de dos elementos. Primero, un healthcheck en el servicio de base de datos que ejecute un comando de diagnóstico real. Para PostgreSQL, por ejemplo, el estándar es pg_isready, que verifica si el servidor acepta conexiones.
En segundo lugar, del lado del servicio de la aplicación, un depends_on con condition: service_healthy. Este le indica a Compose que no cree el contenedor de la app hasta que el healthcheck de la base de datos haya pasado. Entonces, un compose.yaml mínimo y funcional para PostgreSQL se vería así:
services:
db:
image: postgres:16-alpine
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: secret
POSTGRES_DB: app
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 5s
timeout: 5s
retries: 10
start_period: 30s
volumes:
- pgdata:/var/lib/postgresql/data
app:
build: .
depends_on:
db:
condition: service_healthy
restart: true
volumes:
pgdata:
Configura correctamente la base de datos y la aplicación
La configuración anterior corrige el fallo cuando Docker Compose arranca la aplicación antes que la base de datos. La clave está en tres detalles que conviene mirar con cuidado para entender la lógica tras el código. El primero es el doble dólar ($$) en el healthcheck.
Como ya sabrás, Compose interpola las variables de entorno del host antes de pasar el comando al contenedor. Si escribes $${POSTGRES_USER}, Compose deja el literal $${POSTGRES_USER} y el shell dentro del contenedor lo expande con su propia variable. Pero, si escribes ${POSTGRES_USER}, Compose intentará sustituirlo en el host y, si no existe, el comando se ejecutará con un valor vacío y el healthcheck fallará siempre.
El segundo detalle lo ves en los 30 segundos asignados al valor start_period. Este es el tiempo que le das a PostgreSQL para su inicialización, que en un volumen nuevo puede tardar bastante. Durante ese tiempo, los fallos del healthcheck no cuentan para el límite retries. Pero, sin start_period, un retries: 5 con interval: 5s podría marcar la base de datos como unhealthy antes de que termine de arrancar, y Compose abortará el arranque de la app.
Y, si Docker Compose arranca la aplicación antes que la base de datos, el tercer elemento para evitar el fallo es el valor restart: true en la dependencia. Sin esta opción, si reinicias el servicio db con docker compose restart db, la aplicación no se reinicia automáticamente y puede quedarse con conexiones rotas. En cambio, con restart: true, Compose reinicia también los servicios dependientes cuando el servicio del que dependen se actualiza o reinicia bajo su gestión.
Docker Compose arranca la aplicación antes que la base de datos: verifica que la solución funciona
Después de modificar el archivo de Compose, conviene comprobar que la configuración es válida y que los servicios se comportan como esperas. Primero, ejecuta docker compose config para validar y mostrar la configuración resultante. Esto es especialmente útil para detectar errores de sintaxis y problemas con variables de entorno.
Después, inicia los servicios con docker compose up -d –build y, para comprobar el estado de los contenedores, usa docker compose ps. Además, si necesitas consultar los mensajes de la base de datos, ejecuta docker compose logs -f db. Y para revisar los errores de la aplicación, utiliza docker compose logs -f web.
Finalmente, si la base de datos aparece como healthy, pero la aplicación sigue sin conectarse, revisa el nombre del host, las credenciales, el puerto interno y los permisos de usuario. Con esto, ya no sufrirás más porque Docker Compose arranca la aplicación antes que la base de datos.
Conclusión: espera a que la base de datos esté preparada
Cuando Docker Compose arranca la aplicación antes de que la base de datos esté lista, el problema no siempre está en el orden de inicio. En muchos casos, el verdadero inconveniente es que el contenedor de la base de datos ya se está ejecutando, pero todavía no acepta conexiones.
Para evitarlo, utiliza depends_on con condition: service_healthy y configura un healthcheck adecuado para MySQL, PostgreSQL o el motor que emplees. Complementa estas medidas con reintentos de conexión en la aplicación para soportar interrupciones posteriores al arranque.
Desde muy joven he sentido una gran curiosidad por todo lo relacionado con los avances científicos y tecnológicos, en especial aquellos que nos hacen la vida más fácil y entretenida. Me encanta estar al tanto de las últimas novedades y tendencias, y compartir mis experiencias, opiniones y consejos sobre los equipos y gadgets que uso. Esto me llevó a convertirme en redactor web hace poco más de cinco años, enfocado principalmente a los dispositivos Android y sistemas operativos Windows. He aprendido a explicar con palabras simples aquello que resulta complicado para que mis lectores puedan entenderlo fácilmente.