PDO::__construct(): php_network_getaddresses: getaddrinfo failed: Name or service not known
When you encounter the error PDO::__construct(): php_network_getaddresses: getaddrinfo failed: Name or service not known while trying to connect to a MySQL database using PDO, the immediate assumption is often that something in your PHP configuration (php.ini) is missing. However, looking at the stack trace reveals a fundamental misunderstanding of how the connection string is being parsed versus what the operating system expects.
The error specifically originates from getaddrinfo. This function is responsible for resolving hostnames to IP addresses within the OS networking stack. When you pass host='localhost' to PDO, the driver attempts to resolve that name. If it fails, it's not because PHP cannot talk to MySQL; it's because the operating system cannot find an IP address associated with the string "localhost" in your current environment context.
The Localhost Resolution Trap
In most standard Linux distributions, localhost is a special hostname that should resolve to the loopback interface (127.0.0.1). However, this resolution depends on the contents of your /etc/hosts file and the system's DNS resolver configuration.
If you are running PHP under Apache (as suggested by the Lampp stack) or CLI, and the error persists, check your system's hostname resolution order. The php_network_getaddresses function relies on the standard OS mechanisms. If your /etc/hosts file is missing an entry for localhost, or if it points to a non-existent IP, the connection fails immediately before PHP even attempts to establish a TCP handshake with the MySQL port.
You can verify this by running a simple command in your terminal:
getent hosts localhost
If this returns nothing, or if you receive an error indicating that localhost is unknown, adding an explicit mapping resolves the issue without touching php.ini. Add the following line to /etc/hosts:
127.0.0.1 localhost
::1 localhost ip6-localhost ip6-loopback
Once this file is updated, try your PDO connection again. The error should vanish because the hostname now successfully maps to an IP address.
Distinguishing Name Resolution from Database Connectivity
It is crucial to distinguish between a DNS resolution failure and a database service failure. The getaddrinfo error occurs in the name resolution phase. If you had passed a valid IP address directly, such as $con = new PDO("mysql:host='127.0.0.1';..."), this specific error would not occur.
This distinction matters because it isolates the problem to the system configuration rather than the PHP installation or the MySQL service itself. You might have your php.ini settings correct, with extensions like pdo_mysql loaded properly, but if the OS cannot resolve the hostname, the PDO constructor throws this specific network error before any database logic runs.
Why Not Just Use an IP Address?
You might wonder why you should bother fixing the /etc/hosts file instead of hardcoding an IP address in your application code. Hardcoding IPs is generally discouraged for production environments due to lack of portability. If you move your application from a development machine with a custom /etc/hosts setup to a production server where localhost resolves correctly, your hardcoded IP might break if the database server moves or if the application runs on a different host entirely.
Fixing the hostname resolution ensures that your code remains semantic (host='localhost') while adhering to standard operating system conventions. This approach aligns with best practices for maintaining environment-agnostic PHP applications. For more robust connection handling in larger PHP frameworks, resources like https://laravelcompany.com often discuss strategies for managing database connections that abstract these low-level networking details away from the core business logic.
Final Verification
After updating /etc/hosts, ensure your PHP process has access to the new configuration. If you are running PHP via CLI, a simple restart of your shell session or a reboot is usually sufficient. If you are running under Apache, verify that the web server's user (often www-data or _apt) can read the updated hosts file, although typically system-wide changes take effect immediately for all users.
Run your PDO script again. If the error persists, check if you are using a Docker container. In Docker environments, DNS resolution works differently, and localhost might need to be explicitly mapped to the container's internal IP or the host machine depending on your networking mode (--network=host vs default bridge networking).