Docker Compose is a powerful tool that simplifies the deployment of multi-container applications. One common use case is to set up a development environment with services like a web application and a database, such as MySQL. However, orchestrating the startup order of these services can be tricky, especially when ensuring that the application only starts once MySQL is ready to accept connections. This article provides a detailed guide on checking MySQL connection readiness using Docker Compose.

How Docker and Docker Compose Work

Docker is a containerization platform that packages applications and their dependencies into containers. Docker Compose is an orchestration tool that allows you to define and manage multi-container Docker applications using a docker-compose.yml file. This file specifies the services involved, such as a web service and a database service, and how they interact.

The Problem: Ensuring MySQL Readiness

When using Docker Compose to start a service stack, there is a chance that the application container attempts to connect to MySQL before it is ready, resulting in connection errors. This is because services are started simultaneously by default, without any built-in check for service readiness.

Solution: Using a Wait-for-it Script

To solve this issue, a common approach is to use a "wait-for-it" script. This Bash script can block the startup of a dependent service until the MySQL service is ready to accept connections. Below is an example of how to implement this approach:

Step-by-Step Example

1. Create a docker-compose.yml

1    version: '3.8'
2    services:
3      web:
4        build: ./web
5        depends_on:
6          - db
7        entrypoint: ['./wait-for-it.sh', 'db:3306', '--', 'command-to-start-app']
8      
9      db:
10        image: mysql:latest
11        environment:
12          MYSQL_ROOT_PASSWORD: example

1. Add the wait-for-it.sh Script
   Include the following script (available on GitHub) in your web application's directory:

1    #!/usr/bin/env bash
2    host="$1"
3    shift
4    cmd="$@"
5
6    until nc -z "$host"; do
7      >&2 echo "MySQL is unavailable - sleeping"
8      sleep 1
9    done
10
11    >&2 echo "MySQL is up - executing command"
12    exec $cmd

This script checks if MySQL is listening on its standard port and only then proceeds to execute the given command, such as starting a web server.

1. Modify Dockerfile
   In the Dockerfile of your web application, make sure the wait-for-it.sh script is included in the container and executable:

    FROM some-web-image
    COPY wait-for-it.sh /usr/local/bin/
    RUN chmod +x /usr/local/bin/wait-for-it.sh

Key Points Summary

Additional Considerations

1. Alternative Scripts:
   There are other similar scripts, like wait-for, that offer similar functionality. The concept is generally the same; a pause until the service is ready.
2. Docker Compose Wait-for Built-in:
   Newer versions of Docker Compose have started supporting healthcheck:

1      db:
2        image: mysql:latest
3        environment:
4          MYSQL_ROOT_PASSWORD: example
5        healthcheck:
6          test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
7          interval: 10s
8          timeout: 5s
9          retries: 5

However, the depends_on is still based only on startup, not service readiness.

1. Environment-specific Adjustments:
   Consider adjusting the wait mechanism for different environments (dev, prod) and adapt your solution according to network speeds, database load, etc.

By combining these techniques, you can ensure robust multi-container deployments with Docker Compose, even when dealing with intricate inter-service dependencies, like ensuring MySQL is fully ready before another service connects to it. This increases application reliability, decreases errors, and helps streamline the development workflow.