Error Establishing a Database Connection: What It Actually Means

This message means PHP reached your server but could not open the database. The page is not broken — WordPress never got far enough to build one. There are four reasons it happens, and checking them in order finds it quickly.

First: is it everywhere, or just the front end?

Visit /wp-admin. If the admin shows a different message — something about repairing the database — you have a corrupted table rather than a connection problem, and you can skip to the last section.

1. Check the credentials

Open wp-config.php and read the four values. Then verify them against your host panel rather than against memory:

define( 'DB_NAME', 'your_db' );
define( 'DB_USER', 'your_user' );
define( 'DB_PASSWORD', 'your_password' );
define( 'DB_HOST', 'localhost' );

DB_HOST is the one that catches people. It is localhost on most shared hosting, but managed hosts and cloud providers frequently use a separate hostname, an IP, or a socket path. After a migration it is almost always this value.

2. Test the connection independently

Confirm whether the credentials work at all, outside WordPress:

# over SSH
mysql -h localhost -u your_user -p your_db

# or with WP-CLI
wp db check

If that connects, the credentials are right and the problem is elsewhere. If it fails with “access denied”, the username or password is wrong. If it fails with “can’t connect”, the host value is wrong or the database server is down.

3. Is the database server running?

On a VPS you can check directly. On shared hosting you cannot, and the host panel or status page is your source:

systemctl status mysql
# or
systemctl status mariadb

If the service is stopped, starting it fixes the site — but find out why it stopped. The usual cause is the server running out of memory, which will happen again.

4. Connection limit reached

If the site works intermittently, failing under traffic and recovering when it quietens, you are hitting the maximum connection count. The error is identical, which is why this one gets misdiagnosed.

• Enable page caching so most visits never touch the database.
• Check for a plugin opening connections without closing them.
• Ask your host what the limit is and whether you are hitting it.
• Look at whether something is scanning the site and generating uncacheable requests.

5. A corrupted table

If the admin suggests repairing the database, add this to wp-config.php, visit the repair URL, run it, then remove the line again:

define( 'WP_ALLOW_REPAIR', true );
// then visit /wp-admin/maint/repair.php
// then delete this line

A cleaner approach if you have command-line access:

wp db repair
wp db optimize

Quick diagnosis

What you see	Cause
Started right after a migration	DB_HOST or credentials
Front end and admin both down	Credentials, or the server is down
Admin mentions repairing the database	Corrupted table
Comes and goes with traffic	Connection limit
Started after a plugin update	That plugin, probably leaking connections

Common questions

Can I lose data?

Rarely. A connection failure does not delete anything. Corruption can, which is why you take a backup before running a repair.

Why did this start on its own?

Usually a host-side change — a server restart, a password rotation, or a limit being enforced.

Should I increase max_connections?

Only on your own server, and only after confirming caching is working. Raising the limit without fixing the cause moves the failure to memory exhaustion.