Laravel SQLSTATE[HY000] [2002] Connection refused
Encountering SQLSTATE[HY000] [2002] Connection refused during a migration on a DigitalOcean VPS is a classic deployment hurdle that usually points to a network configuration issue rather than a database engine failure. When you see this error while running php artisan migrate, the application cannot establish a TCP handshake with the MySQL server. In many cases involving VPS setups, the culprit is not the database itself but the firewall blocking traffic on port 3306.
Consider a scenario where you have successfully uploaded your Laravel project and configured your .env file with DB_HOST set to your public IP address. You might assume that because you can SSH into the server via port 22, the database is accessible. However, cloud providers like DigitalOcean default their firewalls to a locked-down state, permitting only traffic on ports 80, 443, and 22. When Laravel attempts to connect from the outside world (or even from within the same host if the loopback interface isn't explicitly configured), the connection request is dropped by the kernel firewall before it ever reaches mysqld.
To resolve this, you must adjust the server's firewall rules. Using the DigitalOcean droplet management console or the ufw utility, you need to add an inbound rule for MySQL traffic. If you are using UFW, execute the following command:
sudo ufw allow 3306/tcp
Alternatively, if you are managing the firewall directly via iptables or Cloud Firewall services, ensure that port 3306 is explicitly whitelisted. Once the firewall allows the traffic, restart your web server or clear Laravel caches if necessary, then retry the migration command.
However, simply opening port 3306 to the world introduces security risks. A best practice when deploying a database on a VPS is to bind the MySQL service to 127.0.0.1 and configure your application to connect via localhost, or ensure that the firewall restricts access to specific source IPs if external connection is strictly required. Binding MySQL to 0.0.0.0 with an open firewall exposes the root account to potential brute-force attacks unless you have implemented strong authentication policies and network segmentation.
Another common pitfall involves the user permissions defined within MySQL itself. By default, many installations create a root user that only accepts connections from localhost. If your application connects via the public IP (which resolves to 127.0.0.1 or the actual external IP depending on DNS resolution), the server might reject the connection with an "Access denied" error distinct from a connection refused error, but still indicative of misconfiguration.
You can verify the host configuration by running:
SELECT user, host FROM mysql.user;
If you see root@localhost but your application is trying to connect via the public IP, you may need to grant privileges for that specific host or modify the connection string in your .env file. If you are deploying a single-server setup where the web app and database reside on the same machine, it is often safer to use 127.0.0.1 as the DB_HOST instead of the public IP. This forces the connection through the loopback interface, bypassing external firewall rules entirely while maintaining security isolation from remote hosts.
Finally, ensure that the MySQL service is actually running and listening on the expected port:
sudo systemctl status mysql
netstat -tulpn | grep:mysql
If the service is down or listening on a different port than configured in your .env file, update the configuration accordingly. Addressing these network and permission layers systematically will resolve the Connection refused error and stabilize your deployment pipeline.
