Health Check for MySQL in a Docker Container

Glossary Docker MySQL Background When launching a full-stack web application, whether locally or in production, sequencing the dependencies is critical. For example, if we start serving web pages before the back-end services are ready, users may encounter broken links, 500 errors, or timeout issues that can be hard to debug. Docker provides a built-in mechanism called HEALTHCHECK, which allows us to ensure that the database is ready to accept connections before exposing the REST API endpoints. The Not-So-Perfect Way One obvious way to health-check a MySQL database is to use mysqladmin ping. services: mydb: image: mysql environment: MYSQL_ROOT_USER: root MYSQL_ROOT_PASSWORD: password healthcheck: test: mysqladmin ping interval: 1s However, according to the official documentation, mysqladmin ping would: Check whether the server is available. The return status from mysqladmin is 0 if the server is running, 1 if it is not. This is 0 even in case of an error such as Access denied, because this means that the server is running but refused the connection, which is different from the server not running. It implies that mysqladmin ping is not a reliable way to check readiness. It could lead to intermittent REST API errors, which can be challenging to detect and diagnose. We can validate such behavior by inspecting the Docker container: The Better Way Instead of simply pinging the server, a better health check is to send an actual SQL query to ensure the database is ready to handle requests. test: mysql --user=root --password=password --execute="SHOW DATABASES;" When inspecting the Docker container, we can observe the transition of the exit code from 1 (unavailable) to 0 (ready), indicating the database is now fully operational: Conclusion mysqladmin ping could return a false positive, indicating the server is running even when it's not ready to serve queries. Use SHOW DATABASES; to verify the database is ready to accept connections and handle requests. Have you encountered any issues with MySQL health checks in Docker? Or do you have any tips to share? Drop a comment below and let us know your experiences! We’d love to hear from you.

Apr 3, 2025 - 13:57

Health Check for MySQL in a Docker Container

Glossary

Docker
MySQL

Background

When launching a full-stack web application, whether locally or in production, sequencing the dependencies is critical. For example, if we start serving web pages before the back-end services are ready, users may encounter broken links, 500 errors, or timeout issues that can be hard to debug.

Docker provides a built-in mechanism called HEALTHCHECK, which allows us to ensure that the database is ready to accept connections before exposing the REST API endpoints.

The Not-So-Perfect Way

One obvious way to health-check a MySQL database is to use mysqladmin ping.

services:
  mydb:
    image: mysql
    environment:
      MYSQL_ROOT_USER: root
      MYSQL_ROOT_PASSWORD: password
    healthcheck:
      test: mysqladmin ping
      interval: 1s

However, according to the official documentation, mysqladmin ping would:

Check whether the server is available. The return status from mysqladmin is 0 if the server is running, 1 if it is not. This is 0 even in case of an error such as Access denied, because this means that the server is running but refused the connection, which is different from the server not running.

It implies that mysqladmin ping is not a reliable way to check readiness. It could lead to intermittent REST API errors, which can be challenging to detect and diagnose.

We can validate such behavior by inspecting the Docker container:

The Better Way

Instead of simply pinging the server, a better health check is to send an actual SQL query to ensure the database is ready to handle requests.

test: mysql --user=root --password=password --execute="SHOW DATABASES;"

When inspecting the Docker container, we can observe the transition of the exit code from 1 (unavailable) to 0 (ready), indicating the database is now fully operational:

Conclusion

mysqladmin ping could return a false positive, indicating the server is running even when it's not ready to serve queries.
Use SHOW DATABASES; to verify the database is ready to accept connections and handle requests.

Have you encountered any issues with MySQL health checks in Docker? Or do you have any tips to share? Drop a comment below and let us know your experiences! We’d love to hear from you.