Error establishing a database connection in WordPress: what it means

What the message says

For every page it serves, WordPress opens a connection to its MySQL or MariaDB database using four values written in wp-config.php, at the site root:

define( 'DB_NAME', 'database_name' );
define( 'DB_USER', 'username' );
define( 'DB_PASSWORD', 'password' );
define( 'DB_HOST', 'localhost' );

"Error establishing a database connection" means that connection failed. Four causes produce it: credentials that no longer match, a database server that is down or unreachable, a server that is overloaded, or a damaged database. The sections below go through them from the easiest to check to the rarest.

1. Is the database server responding?

• Your host’s status page: an outage or maintenance on the MySQL server is announced there.
• Other sites on the same account: if they show the same error at the same moment, the cause is on the server side, and the fix is with your host.
• phpMyAdmin, from your hosting panel: if it opens the database and shows its tables, the server is running and the database exists.

If the server is at fault, open a ticket with your host, giving the time the failure started and the exact message. There is nothing to change on the site in the meantime.

2. Are the wp-config.php credentials right?

This is the most frequent cause after moving a site, changing the database password in the hosting panel, or restoring a backup. Compare the four values in wp-config.php with the databases section of your hosting panel:

• DB_NAME and DB_USER: many hosts prefix them with the account name (account_wordpress). The prefix is part of the name.
• DB_PASSWORD: when in doubt, set a new password for the user in the panel, and copy it into the file.
• DB_HOST: localhost at many hosts, though not all. Some give a server name or an address, sometimes followed by a port (:3306). The exact value is in the panel.
• The user needs rights on the database: in the panel, check that the user is attached to the database, with all privileges.

A password containing a single quote (') cuts off the PHP string around it in wp-config.php. Put a backslash in front of it (\'), or choose a password without a single quote.

Test the credentials outside WordPress

WordPress shows a generic message. MySQL, on the other hand, says exactly what is wrong. Two ways to ask it, with the values from wp-config.php:

From the command line, if you have SSH access

mysql -h localhost -u username -p database_name

With WP-CLI, wp db check reads wp-config.php directly and checks the tables with those credentials.

With a temporary PHP file

Upload this file to the site root under a name that is hard to guess, open it in your browser, then delete it straight away: it contains the database password.

<?php
mysqli_report(MYSQLI_REPORT_OFF);
$link = @mysqli_connect('localhost', 'username', 'password', 'database_name');
echo $link ? 'Connection OK' : 'Failed: ' . mysqli_connect_error();

The first line matters: since PHP 8.1, a failed connection throws an exception by default, and the page would stay blank instead of showing the MySQL message.

3. A damaged database: the repair tool

When the credentials are right but tables are damaged, the public site shows the same connection error, and the dashboard a more precise one: "One or more database tables are unavailable. The database may need to be repaired." WordPress ships a tool for this. Add this line to wp-config.php:

define( 'WP_ALLOW_REPAIR', true );

Then open https://www.your-site.com/wp-admin/maint/repair.php and run "Repair Database". Remove the line as soon as the repair is done: while it is there, anyone can reach that page, without logging in.

Before any repair, export the database (wp db export, or the Export tab in phpMyAdmin). If the repair fails, your host can restore the database from its backups.

4. An error that comes and goes: load

An error that shows up at certain times and then clears on its own points to an overloaded server rather than a wrong setting. The usual causes:

• A traffic spike, often bots: repeated login attempts on wp-login.php or xmlrpc.php, visible in your host’s access logs.
• Shared hosting limits: simultaneous connections or processes capped per account. Hosting panels usually show them in their resource usage section.
• A heavy plugin: statistics, logs or scheduled tasks writing to the database on every visit.

The fixes: block abusive login attempts, add page caching, disable xmlrpc.php if no application uses it, and ask your host for the logs covering the time of the error.