Diagnosing 'Error Establishing a Database Connection' in WordPress

The Connection Failure Problem

The "Error Establishing a Database Connection" message is a generic failure state. It indicates that the WordPress PHP application cannot communicate with the MySQL or MariaDB database server. Because this error masks several distinct failure points—ranging from simple typos in a config file to server-level resource exhaustion—you cannot fix it without first isolating where the handshake is failing.

Diagnostic Matrix: Identifying the Root Cause

Symptom	Likely Cause	Diagnostic Focus
Error appears on front-end AND admin dashboard	Server down or wrong credentials	Service status & wp-config.php
Error appears only on front-end; admin shows "One or more database tables are unavailable"	Database corruption	Table integrity checks
Intermittent connection drops under high traffic	Resource exhaustion (OOM)	RAM usage & MySQL logs
Connection timeout (long hang before error)	Network/Firewall block	Port 3306 connectivity

Step 1: Validate Application Credentials

The most common cause is a mismatch between the wp-config.php file and the database user permissions. Before changing any code, verify the credentials manually via the command line.

Run this command from the server terminal (replace placeholders with values found in your wp-config.php):

# Run as a user with shell access to the server
mysql -u [db_user] -p -h [db_host] [db_name]

• Expected Result: You are prompted for a password and successfully enter the MySQL monitor.
• Failure: If you receive "Access denied," the username, password, or host permissions in wp-config.php are incorrect.
• Risk: Do not edit wp-config.php without a backup. A single missing semicolon or quote will trigger a White Screen of Death (WSOD).

Step 2: Verify Database Service Status

If the manual login fails with "Can't connect to MySQL server," the service itself may be stopped or crashed due to an Out-of-Memory (OOM) event.

Check the service status using the system manager (requires sudo/root permissions):

# For systemd-based systems (Ubuntu, CentOS 7+)
systemctl status mysql
# OR
systemctl status mariadb

If the service is inactive or failed, attempt a restart: sudo systemctl restart mysql. If it crashes again immediately, check the system logs (/var/log/syslog or dmesg) for "Out of memory: Kill process" to determine if the server requires more RAM.

Step 3: Test Network and Port Connectivity

In decoupled environments where the database lives on a separate server, a firewall may be blocking port 3306 (the default MySQL port).

Test the connection from the web server to the database server:

# Run from the web server terminal
telnet [db_host] 3306

If the connection times out or is refused, verify that the database server's security group or firewall allows incoming traffic from the web server's IP address on port 3306.

Step 4: Repair Corrupted Tables

If you can access /wp-admin/ but see a database repair notice, the connection is working, but the data is unreadable. This often happens after an unclean server shutdown.

Enable the built-in WordPress repair tool by adding this line to wp-config.php, just before the "That's all, stop editing!" line:

define('WP_ALLOW_REPAIR', true);

Navigate to http://yourdomain.com/wp-admin/maint/repair.php and select "Repair and Optimize Database." Crucial: Remove the WP_ALLOW_REPAIR line immediately after finishing to prevent unauthorized users from triggering repairs.

Summary of Fixes

• Wrong Credentials: Update DB_USER and DB_PASSWORD in wp-config.php to match the MySQL user table.
• Service Crash: Restart the service and increase server RAM or optimize my.cnf to prevent OOM kills.
• Host Mismatch: Change DB_HOST from localhost to 127.0.0.1 if the MySQL socket is misconfigured.
• Corruption: Use the mysqlcheck utility or the WP_ALLOW_REPAIR constant to fix tables.

Escalation Criteria

If the following conditions persist, escalate to a database administrator or hosting provider:

• The MySQL service fails to start even after clearing the /tmp directory and checking disk space.
• Manual CLI login works, but WordPress continues to report a connection error (indicates a PHP-MySQL driver mismatch).
• The database logs show "InnoDB: Database page corruption on disk," which requires binary log recovery.