“Error Establishing a Database Connection” in WordPress: How to Fix It

Is the error on the whole site or only the front end?

Open both your homepage and /wp-admin. If both show the same error, WordPress can’t reach the database at all, so check the connection details and the database server. If wp-admin shows a different message, saying one or more database tables are unavailable and may need to be repaired, the connection works and the tables are damaged. Skip to the repair step.

How do you check the database settings in wp-config.php?

Open wp-config.php in your site’s root folder and find the four database settings. Compare each one with the database and user listed in your hosting panel, for example MySQL Databases in cPanel. A single wrong character in the password is enough to cause the error. Passwords are case-sensitive.

DB_HOST is usually localhost, but some hosts use a separate database server with its own address and sometimes a port. Your host’s documentation or welcome email lists the right value. If you changed the database user’s password in the panel, update wp-config.php to match.

define( 'DB_NAME', 'database_name' );
define( 'DB_USER', 'database_user' );
define( 'DB_PASSWORD', 'database_password' );
define( 'DB_HOST', 'localhost' );

How do you test the database connection directly?

Upload a small PHP file with a random name to your site’s root, fill in the same four values as wp-config.php, and open it in a browser. If it prints “Connected”, the details are right and the problem is in WordPress, usually damaged tables. If it shows an error, the message tells you whether the user, password or host is wrong, or whether the server can’t be reached.

Delete the file as soon as you have the answer: it contains your database password.

<?php
$db = mysqli_connect( 'localhost', 'database_user', 'database_password', 'database_name' );
echo $db ? 'Connected' : 'Error: ' . mysqli_connect_error();

Is the database server down?

If the details are right but nothing can connect, the MySQL or MariaDB server is probably stopped or overloaded. On shared hosting you can’t restart it yourself: contact your host and tell them the exact error and the time it started. On a VPS, check and restart the service, and look at its log for the reason it stopped, often a full disk or the server running out of memory.

sudo systemctl status mysql      # or: mariadb
sudo systemctl restart mysql
df -h                            # a full disk stops MySQL

How do you repair the WordPress database?

WordPress has a built-in repair tool. Add the line below to wp-config.php, then open /wp-admin/maint/repair.php on your site and choose Repair Database. With SSH, wp db repair does the same using the details in wp-config.php.

Remove the line as soon as the repair has finished. The repair page doesn’t require a login, so anyone who finds it can run it while the setting is on.

define( 'WP_ALLOW_REPAIR', true );

wp db check
wp db repair

What if the error comes and goes with traffic?

An error that appears at busy times and then clears usually means the database is refusing new connections because it has reached its limit, or the server is running out of memory. MySQL reports this as “Too many connections”. Common triggers are traffic spikes, aggressive bots and slow plugin queries holding connections open.

Block abusive bots, add page caching so fewer requests reach the database, and look for slow queries. If the site has simply outgrown its plan, move to hosting with more resources.

Did the error start after moving to a new host?

After a migration, wp-config.php often still holds the old host’s database details, or the database was never imported. Create the database and user on the new host, import the database export, then update all four settings in wp-config.php. If the domain also changed, update the site URL in the database before testing.

When should you restore a backup?

Restore a database backup if tables can’t be repaired or data is missing. Restore the most recent backup from before the problem, ideally on a staging copy first. Then find the cause, such as a full disk or a failed update, so the error doesn’t return.