Resolving PHP Database Connection Error: php_network_getaddresses: getaddrinfo failed

Error Phenomenon and Background

In PHP application development, database connectivity is a core functionality. A common error scenario occurs when using the mysqli extension to connect to a MySQL database, resulting in the error message "Connection failed: php_network_getaddresses: getaddrinfo failed: Name or service not known." This error typically arises when network address resolution fails, indicating that PHP cannot resolve the provided server name into a valid network address.

Case Analysis: Incorrect Server Address Configuration

Consider the following typical connection code that attempts to establish a connection to a MySQL database:

<?php
$servername = "http://www.url.com";
$username = "db_username";
$password = "db_password";
$databaseName = "db_name";

$connect = new mysqli($servername, $username, $password, $databaseName);

if ($connect->connect_error) {
    die("Connection failed: " . $connect->connect_error);
}
echo "Connected successfully";
?>

In this code, $servername is set to a full URL (http://www.url.com) instead of a valid hostname. The mysqli constructor expects a hostname (e.g., localhost or 192.168.1.1), not a URL with a protocol prefix. This causes PHP's network functions to fail in resolving the address, triggering the aforementioned error.

Root Cause: Confusion Between Hostname and URL

The core of this error lies in confusing hostnames with URLs. A hostname is a simple string used to identify a computer on a network, such as localhost or www.example.com. A URL (Uniform Resource Locator) is a complete network address, including protocol (e.g., http://), hostname, path, and other components. In the context of database connections, only the hostname is required, as database connections use specific protocols (like MySQL protocol) rather than HTTP.

When the database server resides on the same machine as the web server, the correct hostname is localhost. This is a special reserved hostname that points to the local machine. If the database server is on a remote machine, the IP address or domain name of that machine should be used (e.g., 192.168.1.100 or db.example.com), but without the http:// prefix.

Solution: Using the Correct Hostname

Based on best practices, the corrected code should appear as follows:

<?php
$servername = "localhost"; // For local databases
$username = "db_username";
$password = "db_password";
$databaseName = "db_name";

$connect = new mysqli($servername, $username, $password, $databaseName);

if ($connect->connect_error) {
    die("Connection failed: " . $connect->connect_error);
}
echo "Connected successfully";
?>

This modification changes $servername from http://www.url.com to localhost, resolving the address resolution issue. In actual deployments, if the database is on a remote server, replace localhost with the appropriate IP address or domain name.

In-Depth Understanding: Network Address Resolution Mechanism

When establishing a connection, PHP's mysqli extension calls underlying network functions to resolve the hostname. This process involves the operating system-level getaddrinfo function, which attempts to convert the hostname into an IP address. When an invalid hostname (such as a string containing http://) is provided, resolution fails, causing the error.

For more robust code, consider adding error handling and configuration flexibility:

<?php
function connectToDatabase($host, $user, $pass, $db) {
    $conn = new mysqli($host, $user, $pass, $db);
    if ($conn->connect_error) {
        error_log("Database connection failed: " . $conn->connect_error);
        return null;
    }
    return $conn;
}

$servername = getenv('DB_HOST') ?: "localhost"; // Read from environment variable, default to localhost
$connect = connectToDatabase($servername, $username, $password, $databaseName);
if (!$connect) {
    die("Unable to connect to database");
}
?>

This approach allows dynamic configuration of the database host via environment variables, enhancing code portability and security.

Supplementary Discussion: Other Common Configuration Issues

Beyond hostname errors, the php_network_getaddresses error can also be caused by:

• DNS Resolution Failure: If using a domain name (e.g., db.example.com) and the DNS server cannot resolve it, a similar error may occur. Solutions include checking DNS configuration or using IP addresses directly.
• Network Firewall Restrictions: Firewalls may block access to the database port (default 3306). Ensure network rules permit the connection.
• PHP Configuration Issues: In some cases, PHP's allow_url_fopen setting might affect network address resolution, though this is not a primary cause.

As a reference, another answer notes: "The value you've specified for $servername is not a host name but rather a URL, or resource name. The host name would be just www.url.com." This emphasizes the importance of distinguishing between hostnames and URLs, but in local development environments, localhost is often the more appropriate choice.

Security and Best Practice Recommendations

While fixing connection errors, adhere to the following security best practices:

1. Use Prepared Statements: In the example insert.php, SQL queries concatenate user input directly, posing SQL injection risks. Use prepared statements instead:

   $stmt = $connect->prepare("INSERT INTO demo (name, lastname, age) VALUES (?, ?, ?)");
   $stmt->bind_param("ssi", $name, $lastname, $age);
   $stmt->execute();

2. Avoid Hard-Coded Credentials: Store database credentials in configuration files or environment variables, not directly in code.
3. Error Handling: In production environments, avoid using die() to output error messages directly, as it may leak sensitive information. Use logging instead.

Conclusion

The "php_network_getaddresses: getaddrinfo failed: Name or service not known" error typically stems from incorrect hostname configuration. By setting $servername to localhost (for local databases) or a valid IP address/domain name (for remote databases), this issue can be resolved. Developers should clearly distinguish between hostnames and URLs and adopt secure coding practices to build robust database connections. The code examples and explanations provided in this article aim to help readers deeply understand the nature of this common error and its solutions.