Error establishing a database connection: how to fix it

"Error establishing a database connection" means WordPress could not talk to MySQL. That's all it means. The message is identical whether your credentials are wrong, the database server is down, the database is corrupted, or the host has cut you off for using too many resources — which is why generic fixes so often miss.

Work through the causes in order. It takes about two minutes to find which one you have.

First, check whether the database server is even up

If your host gives you phpMyAdmin or Adminer, try logging in. If that fails too, WordPress isn't your problem — the database server is down or unreachable, and this is a hosting issue rather than a site issue.

On a server you control, check the service directly:

systemctl status mysql

A stopped service is usually either a crash after running out of memory, or a disk that has filled up. Check both before restarting, or you will be doing this again within the hour:

df -h
free -m

A full disk is the single most common cause I see on small VPS installations, and it is often the logs that filled it.

Then check the credentials

WordPress reads four values from wp-config.php:

define( 'DB_NAME', '...' );
define( 'DB_USER', '...' );
define( 'DB_PASSWORD', '...' );
define( 'DB_HOST', 'localhost' );

These break after a migration, after a host resets a password, or after someone edits the file and leaves a stray character. Compare each against what your hosting panel shows.

DB_HOST is the one people get wrong. It is localhost on most shared hosting, but managed hosts frequently use a dedicated hostname, and some require a port or socket path. Copy it exactly rather than assuming.

Test the credentials independently

Rather than editing wp-config.php repeatedly and reloading the site, test the connection on its own:

mysql -u DB_USER -p -h DB_HOST DB_NAME

If that connects, your credentials are fine and the fault is elsewhere. If it rejects you, you have found the problem, and no amount of WordPress troubleshooting would have helped.

Rule out a corrupted database

If the site loads but the admin shows a different message — often mentioning that the database needs repairing — you likely have a crashed table. WordPress has a built-in repair mode. Add this to wp-config.php:

define( 'WP_ALLOW_REPAIR', true );

Then visit /wp-admin/maint/repair.php and run the repair.

Remove that line as soon as you're done. The repair page is deliberately accessible without logging in, so leaving it enabled leaves a maintenance tool exposed to anyone who finds the URL.

With WP-CLI the same job is cleaner, and doesn't expose anything:

wp db repair

Consider resource limits

On shared hosting, a burst of traffic or one expensive query can push you past a connection limit. The site then fails intermittently — fine on reload, broken a minute later — which is the signature symptom.

Intermittent failures point at limits or a struggling server, not at configuration. Configuration problems are consistent: wrong credentials fail every single time. If yours comes and goes, look at load, slow queries, and whatever your host reports for resource usage.

What not to do

• Don't reinstall WordPress. The error is about connecting to the database. Replacing core files changes nothing and risks your customisations.
• Don't restore an old backup as a first move. You will lose recent content to fix something that is often a one-line credential change.
• Don't paste wp-config.php into a support forum. It contains your database password. If you already have, change that password.

Keeping it from recurring

If it was disk space, add monitoring and log rotation. If it was a crashed table, check whether the server is being shut down uncleanly. If it was resource limits, the honest answer is usually that the site has outgrown its plan — no amount of tuning fixes an underpowered box forever.

For the routine work that catches most of this early, see a WordPress maintenance checklist that prevents problems.