Error establishing a database connection

Symptoms

The page says "Error establishing a database connection" or "Error connecting to database." It is usually the whole site, not one page. Sometimes it appears after a host move, a MySQL upgrade, or a config edit; sometimes it appears all at once for no obvious reason.

Common causes

• The wp-config DB_NAME, DB_USER, DB_PASSWORD, or DB_HOST value does not match what the database server accepts.
• The database server is down, restarted, or rejecting connections from the web server's host.
• The database user lacks privileges, or the password changed and wp-config still holds the old one.
• The host string is wrong. Common examples: localhost when the database server is on another host, or a port and socket that do not match.
• The table prefix in wp-config does not match what is in the database.
• Query limits or connection limits are exhausted during load spikes.
• The tables themselves are intact but the connection attempt fails before any query runs, which points at authentication or network, not data loss.

How to fix

1. Check whether the database server is reachable from the command line or a host tool such as phpMyAdmin using the same credentials WordPress uses. If you cannot connect there either, the problem is the server or the credentials, not the site.
2. Verify the credentials. Edit wp-config.php with a text editor, not the browser editor. Confirm each constant against your host's provided values, including the host value, which is often not localhost.
3. Test with a database client or a short script. A one-line PHP file that calls mysqli_connect(DB_HOST, DB_USER, DB_PASSWORD, DB_NAME) prints the real error instead of the generic message. Delete it after testing.
4. Restart the database service if the host offers restart access, or raise an incident with the host if they run it.
5. Check for an unmatched table prefix: the value of $table_prefix in wp-config must match the prefix of the tables in the database (usually wp_).
6. Be careful with downtime during a move. If you changed hosts or IPs, the old and new server may be fighting over the connection, or a firewall may be blocking the new database host.
7. Review resource limits if the error is intermittent under load. Some shared hosts kill long-running or too many concurrent connections.

Prevention

• Keep a recent copy of wp-config outside the web root, for example in your repo as an untracked example, so a bad edit is reversible.
• Store the database on the same host or a low-latency private network when you control the architecture.
• Trap connection failures early with a small health check, so a failed connection shows a maintenance page instead of the raw error.