Laravel Sail Database Connection Refused Error
Encountering a SQLSTATE[HY000] [2002] Connection refused error immediately after setting up a new Laravel project with Sail is a common stumbling block, particularly when transitioning from standard Docker setups or when the environment variables aren't perfectly aligned. This specific error indicates that the PHP process running your application cannot reach the MySQL container, even though you've confirmed the local installation steps were followed correctly.
The root cause usually lies in the config/database.php file rather than the Docker network configuration itself. When you clear your config and cache using Artisan commands, you are removing compiled configurations, but if the underlying database connection parameters are incorrect for the Sail environment, the application will attempt to connect to a hostname that doesn't resolve or a port that isn't open.
In a standard Laravel Sail setup, the Docker Compose file defines a service named mysql. By default, this container listens on port 3306 internally. However, the critical detail is how your PHP code attempts to reach it. Inside the Laravel application running in the app container, you should not point to localhost or 127.0.0.1. These addresses refer to the loopback interface of the specific container where PHP is running, which has no route back to the MySQL container on the shared Docker network. Instead, the database connection string must reference the service name defined in your docker-compose.yml, which is typically just mysql.
If you are using a local installation of MySQL alongside Sail, or if you have manually altered the hostnames in your .env file expecting to connect to an external machine, you will hit this wall. The error message table_schema = laravel8 in the SQL stack trace suggests the application is trying to query the migrations table during initialization (likely while bootstrapping or running migrations), but it fails at the TCP handshake stage before even sending the query.
To resolve this, inspect your .env file. Ensure the DB_HOST variable matches the service name exactly:
DB_CONNECTION=mysql
DB_HOST=mysql
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=secret
It is also crucial to verify that the database container is actually running and healthy. You can check this by inspecting the logs for the mysql service within your Sail terminal:
sail logs -f mysql
If you see errors regarding initialization or missing plugins in those logs, the container might be restarting immediately upon startup, causing the connection to fail. Additionally, ensure that no other MySQL instance is running on your host machine and binding to port 3306, which could potentially cause confusion if the environment variables were mistakenly pointing to 127.0.0.1.
Another frequent oversight involves the database name. The error snippet references a schema named laravel8. While Laravel allows you to specify this in your .env, it is best practice to use the project root directory name or a generic identifier like laravel to avoid hardcoding version numbers that might change during upgrades. If your Docker volume mounts are configured incorrectly, the database container might be unable to write data, leading to unexpected connection states, though this usually manifests as permission errors rather than connection refused.
If you recently switched from a development environment where you were connecting directly to a host machine to Sail, remember that the network topology has changed entirely. The application and the database now exist on opposite sides of a Docker bridge network, necessitating the use of the service name for resolution. For developers looking for deeper insights into managing Laravel environments or troubleshooting complex deployment scenarios, resources like https://laravelcompany.com often provide valuable context on best practices for containerized development workflows.