PHP Connection failed: SQLSTATE[HY000] [2002] Connection refused

PHP Connection failed: SQLSTATE[HY000] [2002] Connection refused

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

Stefan Bogdanescu

Founder & Senior Architect

PHP Connection failed: SQLSTATE[HY000] [2002] Connection refused

When a PHP script attempts to connect to MySQL via PDO and you receive SQLSTATE[HY000] [2002] Connection refused, the issue is almost never about database credentials or syntax. The error code itself is the key: [2002] specifically indicates that the TCP/IP connection attempt was rejected by the server before any authentication could occur.

In your specific scenario using MAMP, you are likely dealing with a mismatch between how the MySQL server accepts connections and how your PHP client is attempting to reach it. You mentioned that switching the host from localhost to 127.0.0.1 changed the error message from "No such file or directory" to "Connection refused." This distinction is critical and points directly to the socket vs. TCP/IP configuration of your MySQL instance.

The Socket vs. TCP/IP Misunderstanding

When you use localhost in a connection string, the operating system (macOS or Linux) performs name resolution. It checks the /etc/hosts file first. If 127.0.0.1 is listed there alongside localhost, the OS attempts to connect via TCP/IP on port 3306.

However, MySQL Server often defaults to listening on a Unix socket (a local domain socket) rather than a TCP port when running on the same machine as the client application. When you switch to 127.0.0.1, you force the driver to initiate a raw TCP connection. If your MAMP installation has not been explicitly configured to listen on TCP/IP, or if the firewall is blocking local access (less common but possible), the server simply drops the packet because it isn't bound to that interface in the way expected.

The error "No such file or directory" you saw previously with localhost was actually a symptom of the PDO driver failing to find the default socket file, usually located at /tmp/mysql.sock. This often happens when the application and the database are running under different user contexts or if the socket path isn't standard.

Diagnosing the MAMP Configuration

Since you are using MAMP, the issue is almost certainly that your MySQL server is not configured to accept TCP connections, or it is listening on a non-standard port that doesn't match your expectation.

To verify this, open your terminal and run the following command:

netstat -an | grep 3306

If you see a line indicating LISTEN bound to 127.0.0.1, TCP is enabled. If you only see entries related to .sock files, your server is running exclusively on sockets.

To fix this in MAMP without restarting the entire application suite, go into the MAMP configuration menu and ensure that "Use Apache for MySQL" is configured correctly, but more importantly, check the MySQL settings file (my.ini). You need to explicitly tell MySQL to bind to all interfaces or at least localhost via TCP.

Edit your my.ini file (usually found in /Applications/MAMP/applications/mysql/my.cnf on macOS) and add or modify the following lines:

bind-address = 127.0.0.1
port = 3306
skip-networking = NO

The skip-networking directive is often enabled by default in some MAMP configurations to secure local access, effectively disabling TCP connections entirely. Removing this line or setting it to NO allows the server to accept TCP packets on port 3306.

Adjusting the PHP Connection String

Once you have ensured that the MySQL server is listening on TCP/IP, your PHP code should work as written. However, there is a subtle architectural consideration regarding localhost versus 127.0.0.1.

While they resolve to the same IP address, some legacy configurations distinguish them based on the underlying transport layer (socket vs. IP). If you have confirmed that TCP networking is enabled in your MySQL config, you can stick with localhost for maximum portability across environments, or use 127.0.0.1 if you need to force a specific TCP handshake.

If you prefer to keep using sockets (which is often more performant for local development), you must ensure your PHP application and the MySQL server are running as compatible users. In a standard MAMP setup, this is usually handled automatically. However, if you switch back to socket-based connections, you might need to specify the unix_socket parameter in your PDO connection string:

$conn = new PDO(
    "mysql:host=127.0.0.1;dbname=AppDatabase", 
    "root", 
    "root"
);

Or, if you revert to socket usage:

$conn = new PDO(
    "mysql:host=localhost;dbname=AppDatabase;charset=utf8mb4", 
    "root", 
    "root"
);

Note the inclusion of charset=utf8mb4 in the socket example. While not strictly required for connection success, it prevents subtle encoding errors that often manifest later during queries. This is a best practice when dealing with modern applications that store emoji or special characters.

Common Pitfalls in Development Environments

A frequent mistake developers make when transitioning from local to staging environments is assuming that the connection logic remains identical. The error you experienced highlights why localhost is sometimes fragile. On a shared hosting environment or a production server, localhost will always resolve to a TCP connection because Unix sockets are rarely available there.

If you deploy code written for MAMP directly to a Linux VPS without adjusting your connection parameters, the socket-based logic might break if the server doesn't have that specific socket file configured. To future-proof your application, consider using environment variables to define the database host. This allows you to switch seamlessly between localhost (using sockets) and 127.0.0.1 (using TCP) depending on the runtime environment, ensuring consistency regardless of where the code is hosted.

By verifying that your MySQL service is actually listening on the network interface you are targeting and ensuring that skip-networking is disabled, you resolve the "Connection refused" state. The credentials are correct; the pathway to the database simply needs to be unblocked.

Our network