Docker MYSQL '[2002] Connection refused'

Docker MYSQL '[2002] Connection refused'

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Docker MYSQL '[2002] Connection refused'

When deploying a LEMP stack inside Docker, encountering SQLSTATE[HY000] [2002] Connection refused is a classic symptom of a networking misunderstanding rather than a database configuration error. You are not running out of memory or hitting a license limit; your application simply cannot find the database container on the network it expects to talk to.

The root cause in scenarios like the one described lies in how Docker Compose handles service discovery and port mapping versus how applications resolve hostnames. In your docker-compose.yml, you defined a service named mysql (or mariadb in the image tag, though the service name is still mysql). However, your PHP-FPM container is attempting to connect using the hostname provided in your application's configuration file.

If your Symfony project is configured with 127.0.0.1 or localhost as the database host, it will fail immediately. Within a Docker environment, localhost refers to the loopback interface of the specific container running PHP-FPM, not the host machine, and certainly not other containers in your network. The database service is listening on port 3306 inside its own container namespace, but that port is only accessible via the container's internal IP address or by resolving its Docker service name.

To resolve this, you must change the database host setting in your application configuration from 127.0.0.1 to the exact service name defined in your Compose file: mysql. When both PHP-FPM and the MySQL service are launched using docker-compose up, Docker creates an internal DNS server that allows containers to resolve each other by their service names. This abstraction removes the need to know the actual IP addresses assigned to the containers, which can fluctuate or change upon restart.

There is a secondary consideration regarding port mapping. Your Compose file maps host port 3306 to container port 3306 (- 3306:3306). While this works for connecting from the host machine directly, it does not enable inter-container communication if the host network driver or specific Docker version restricts that behavior. However, since your PHP application and database are both running within the same Docker Compose project (likely on the default default network), they communicate via the internal DNS, bypassing the need for the mapped port entirely. The error persists only because the application is looking at the wrong address.

Another potential pitfall involves the PHP-FPM configuration itself. Your Dockerfile installs the pdo_mysql extension, which is correct. However, ensure that your php.ini or .env files within the PHP container do not have hard-coded connection strings pointing to the host machine. If you are using environment variables to pass database credentials, verify that the DB_HOST variable is set to mysql.

Additionally, check your firewall settings if you attempt to connect from outside the Docker network. The error message specifically indicates a refusal, which often happens when the MySQL service accepts connections but the network path is blocked or the user lacks permission. In the provided source material, the MYSQL_ROOT_PASSWORD is set to admin. Ensure that your application credentials match this exactly and that you are using the root user or a dedicated database user with appropriate grants.

If you are trying to access the database from your local machine outside of Docker, you can connect by navigating to http://localhost:3306 (for CLI tools) or via a client pointing to 127.0.0.1:3306. However, for your application code, sticking to the service name mysql is the robust, container-native approach that prevents these connection errors regardless of host machine network configurations.

For developers working with modern PHP frameworks, this pattern of explicit service naming is standard practice. If you prefer a managed approach or need more advanced networking features beyond the default bridge network, tools like Laravel Sail provide abstractions that handle this DNS resolution automatically, though understanding the underlying mechanics remains essential for troubleshooting when things go wrong.

Our network