Fixing the database connection error

Database Connection Error: Why Does Your Site Suddenly Go Offline?

One of the most frightening moments for any site administrator is seeing a Database Connection Error message. This error usually appears suddenly and blocks access to the entire site. In WordPress, this error is often accompanied by the message "Error Establishing a Database Connection", but in custom PHP applications, you may see different errors like "PDOException: SQLSTATE[HY000] [2002]" or "mysqli::connect(): (HY000/2002)".

The good news is that in most cases, this error is fixable and there is no need to panic. In this article, we will examine seven common causes of Database Connection Error in order of priority and provide practical solutions for each with real commands. This order is designed based on practical experience and the likelihood of each issue occurring.

If you use professional web hosting services like ServerNet, monitoring tools and technical support are usually available to fix this error. But knowing the troubleshooting principles will help you solve the problem in the shortest possible time.

Cause 1: Incorrect Connection Information in the Config File

The most common reason for a Database Connection Error is incorrect connection information. In WordPress, this information is stored in the wp-config.php file. In other PHP applications, files like config.php, .env, or database.php are usually responsible for these settings.

Checking the wp-config.php File in WordPress

Open the wp-config.php file with a text editor and check these four lines:

define('DB_NAME', 'your_database_name');
define('DB_USER', 'your_database_user');
define('DB_PASSWORD', 'your_database_password');
define('DB_HOST', 'localhost');

Common mistakes:

• DB_HOST: If the database is on a separate server, its value should be the IP or domain of the database server (e.g., 192.168.1.100 or db.example.com). Using localhost in this case causes an error.
• DB_PASSWORD: The password may contain special characters that are not interpreted correctly in the PHP string. If the password includes ' (apostrophe), you must escape it with \'.
• DB_NAME: The database name must exactly match the name created in MySQL. Database names are case-sensitive on Linux.

Troubleshooting tip: Create a simple PHP file named test-db.php in the site root and put the following code in it:

<?php
$link = mysqli_connect('localhost', 'your_user', 'your_password', 'your_database');
if (!$link) {
    die('Error: ' . mysqli_connect_error());
}
echo 'Connection successful';
mysqli_close($link);
?>

Then open this file in your browser. If it shows an error, you can see exactly which part the problem is from.

Cause 2: Database Corruption or Deletion

Sometimes the database becomes corrupted for various reasons or is accidentally deleted. This problem is usually accompanied by different errors.

Checking the Existence of the Database and Tables

Connect to the server via SSH or cPanel and enter MySQL with the following command:

mysql -u root -p

Then list the existing databases:

SHOW DATABASES;

If your database is not in the list, you need to rebuild it. If the database exists but the tables are corrupted, use the following command to repair:

mysqlcheck -u root -p --auto-repair --all-databases

Common mistake: Many users assume that if the database is displayed in phpMyAdmin, it must be healthy. But sometimes the internal tables of the database (like wp_options in WordPress) become corrupted and cause a connection error. Always use the mysqlcheck command to check.

Cause 3: Server Resource Limits (MySQL Down)

One of the hidden causes of Database Connection Error is excessive resource consumption by MySQL. When server memory or CPU reaches its maximum, the MySQL service may automatically stop.

Checking MySQL Service Status

On Linux servers, check the MySQL status with the following command:

systemctl status mysql

If the service is not active, start it:

systemctl start mysql

To check MySQL error logs, use the following command:

tail -100 /var/log/mysql/error.log

In this log, you will usually see errors like "Out of memory" or "Too many connections", which indicate resource limitations.

Temporary solution: If your server does not have enough RAM, you can adjust MySQL parameters in the /etc/mysql/my.cnf file. For example, reduce the max_connections value:

[mysqld]
max_connections = 50
innodb_buffer_pool_size = 256M

After making changes, restart the service.

Cause 4: Firewall or IP Restriction

If the database is on a separate server (e.g., a dedicated database server), the database server's firewall may be blocking the connection from your web server's IP.

Checking Remote Access

From the web server, test the connection to the MySQL port (default 3306) with the following command:

telnet your-db-server-ip 3306

If the connection is not established, there is a problem with the firewall or network settings. On the database server, check the iptables rules with the following command:

iptables -L -n | grep 3306

Also, in MySQL, the database user must have permission to connect from the web server's IP. Check with the following command in MySQL:

SELECT host, user FROM mysql.user WHERE user = 'your_user';

If the host value is only localhost, you need to change it to the web server's IP or % (for all IPs):

GRANT ALL PRIVILEGES ON your_database.* TO 'your_user'@'your-web-server-ip' IDENTIFIED BY 'your_password';
FLUSH PRIVILEGES;

Common mistake: Using % for all IPs reduces security. It is better to specify the exact IP of the web server.

Cause 5: Corruption of WordPress or Application Files

Sometimes the core files of WordPress or a PHP application become corrupted, causing a Database Connection Error. This problem usually occurs after an incomplete update or a hacking attack.

Resetting the wp-config.php File

In WordPress, if the wp-config.php file is corrupted, you can replace it with a clean version. First, back up the current file:

cp wp-config.php wp-config.php.backup

Then create a new file from the sample:

cp wp-config-sample.php wp-config.php

Now enter the correct database information in the new file.

For other PHP applications, compare the config files with the original version (usually in the Git repository or installation package).

Cause 6: DNS or Database Hostname Issue

If you use a hostname (e.g., db.example.com) in the connection settings, DNS may not resolve correctly.

Testing DNS Resolution

From the web server, convert the hostname to an IP with the following command:

nslookup db.example.com

If you do not receive a correct response, add a manual mapping in the /etc/hosts file:

192.168.1.100 db.example.com

Then test the connection again.

Cause 7: Incompatible PHP or MySQL Version

Sometimes after updating PHP or MySQL, the versions are not compatible with each other. For example, WordPress 5.0 works well with PHP 8.0, but some older plugins may have issues with the new PHP version.

Checking Versions

Check the PHP version with the following command:

php -v

Check the MySQL version:

mysql --version

Ensure that your application supports these versions. For WordPress, at least PHP 7.4 and MySQL 5.6 are required.

Important note: If you are using MySQL 8, older WordPress plugins may have issues with the new MySQL authentication method (caching_sha2_password). In this case, change the database user to the old method:

ALTER USER 'your_user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your_password';
FLUSH PRIVILEGES;

Final Troubleshooting Order (Checklist)

To quickly fix a Database Connection Error, follow this order:

1. Check the config file (wp-config.php or its equivalent).
2. Check the MySQL service status with systemctl status mysql.
3. Test manual connection with mysql -u user -p.
4. Check the existence of the database and tables with SHOW DATABASES; and mysqlcheck.
5. Test the firewall and IP access with telnet.
6. Read MySQL error logs in /var/log/mysql/error.log.
7. If necessary, restart the MySQL service.

By following these steps, the problem will be resolved in 90% of cases. If the error still persists, the issue is likely related to server hardware or more advanced settings that require review by the technical team.