Resolving 'Error Establishing a Database Connection' in WordPress

The Connection Failure Problem

When WordPress displays "Error Establishing a Database Connection," the PHP application cannot communicate with the MySQL or MariaDB server. This is a critical failure that prevents the site from loading any content, as WordPress relies on the database for every page request. The goal is to isolate whether the failure is due to a crashed service, incorrect credentials, or corrupted data tables.

Quick Diagnostic Matrix

Symptom	Likely Cause	Primary Tool
Error on both frontend and /wp-admin	Service down or wrong credentials	systemctl / wp-config.php
Error only on frontend; /wp-admin shows repair link	Corrupted database tables	WP_ALLOW_REPAIR constant
Intermittent connection drops	Server resource exhaustion (RAM/CPU)	top / htop / error logs

Step-by-Step Diagnostic Sequence

Follow these checks in order to avoid unnecessary configuration changes.

1. Verify Database Service Status

Before checking code, ensure the database engine is actually running. On most Linux-based servers (Ubuntu, CentOS), run the following command as a user with sudo privileges:

sudo systemctl status mysql # Or 'mariadb' depending on your installation

Expected Result: The status should be active (running). If it is inactive or failed, the service has crashed or stopped.

2. Validate wp-config.php Credentials

If the service is running, the issue is likely authentication. Open your wp-config.php file in the WordPress root directory. Locate these constants:

• DB_NAME: The name of the database.
• DB_USER: The database username.
• DB_PASSWORD: The password for that user.
• DB_HOST: The server address (usually localhost).

Risk: Never share the contents of this file in public support forums or logs, as it contains plaintext credentials.

3. Manual Connection Test

To determine if the credentials in wp-config.php are valid, attempt to connect manually via the command line. Replace the placeholders with the values found in your config file:

mysql -u [DB_USER] -p -h [DB_HOST] [DB_NAME]

Run this on the server where WordPress is hosted. After entering the password, if you see the MySQL prompt, the credentials are correct, and the issue may be related to the PHP environment or database corruption.

Applying the Fixes

Fix A: Restarting the Database Service

If Step 1 showed the service was inactive, restart it. This often happens if the server ran out of memory (OOM Killer) and terminated the MySQL process.

sudo systemctl restart mysql

Fix B: Correcting Hostname Resolution

If the manual test failed but you are certain the password is correct, try changing DB_HOST. In some environments, localhost tells PHP to use a Unix socket, while 127.0.0.1 forces a TCP connection.

• Change: define( 'DB_HOST', 'localhost' ); → define( 'DB_HOST', '127.0.0.1' );

Fix C: Repairing Corrupted Tables

If you can access /wp-admin but see a message stating that the database needs repair, WordPress has detected corruption. To enable the built-in repair tool, add this line to your wp-config.php file, 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 click "Repair Database".

Rollback: Once the repair is complete, you must remove the WP_ALLOW_REPAIR line from wp-config.php to prevent unauthorized users from triggering repairs.

Verification and Escalation

To verify the fix, clear your browser cache and attempt to load the homepage. If the site loads, check the WordPress admin dashboard to ensure all plugins are active and data is intact.

When to Escalate

If the following conditions persist, the issue is likely outside the scope of WordPress configuration:

• The database service fails to start even after a restart (check /var/log/mysql/error.log for disk space or permission errors).
• Manual connection via CLI fails with "Access denied" despite verified passwords (indicates a MySQL user privilege issue).
• The site works for a few minutes then crashes again (indicates server resource exhaustion).