Error Establishing a Database Connection in WordPress: An Owner’s Guide

"Error establishing a database connection" means WordPress cannot reach the database that holds your pages, products, orders and settings, so it cannot build any page for your visitors. The usual causes, starting with the most common, are wrong database details in the wp-config.php file (often after a move or a password change), a database server that is down or overloaded, and a damaged database.

The message by itself does not mean your content is gone. Work through the checks below in order.

What does "Error establishing a database connection" mean?

It means WordPress tried to log in to its database and failed. Your site has two parts: the files (WordPress, your theme and your plugins) and a MySQL or MariaDB database that stores the content and settings. On every page view, WordPress connects to the database using four details saved in a file called wp-config.php. If any of them is wrong, or the database server does not answer, WordPress stops.

Visitors see only that one line. WordPress's fuller explanation, shown in the admin area, says either the username and password in wp-config.php are incorrect or the database server could not be reached, which could mean your host's database server is down.

What should you check first?

Before you change anything, find out how much of the site is affected and whether your host already knows about a problem.

• Open several pages, including one you rarely visit. If some pages load and others show the error, a caching plugin or your host's cache is probably serving saved copies of the popular ones. The database is still unreachable, so forms, checkout and logins will fail even where pages appear.
• Visit yoursite.com/wp-admin. The admin area shows WordPress's longer message. If it reads "One or more database tables are unavailable. The database may need to be repaired," WordPress can reach the database but some tables are damaged, so go to cause 3 below. If it repeats the connection error, carry on.
• Check your host's status page and your inbox. Many hosts publish a status page for outages, but a green page does not rule out a problem with your own server. Kinsta, for example, says issues affecting a small number of customers are reported to those customers directly rather than on its public page.
• Ask what changed. A move to a new host, a new database password or a developer's work in the last day points straight to wp-config.php.

What causes the error, and how do you fix it?

Here are the causes, starting with the most common.

1. Wrong database details in wp-config.php

WordPress's documentation says this error is usually caused by a mistake in wp-config.php, typically after a move to a new host or a changed database password.

The file sits in your site's main folder, the one that contains the wp-admin folder (some setups keep it one folder higher). Open it through SFTP or your host's file manager, save a copy before you change anything, and edit it in a plain text editor, not a word processor. Look for four lines like these, with your own values in place of the placeholders:

define( 'DB_NAME', 'database_name_here' );
define( 'DB_USER', 'username_here' );
define( 'DB_PASSWORD', 'password_here' );
define( 'DB_HOST', 'localhost' );

• DB_NAME is the name of the database.
• DB_USER is the database username, a separate login from your WordPress one.
• DB_PASSWORD is that user's password.
• DB_HOST is the database server's address: usually localhost, but some hosts use a separate server name, sometimes followed by a colon and a port number.

Compare each value with your hosting control panel. In cPanel, that is Databases > Manage My Databases (called MySQL Databases in older versions). On many hosts, database and user names begin with your account name and an underscore, so names copied from an old host will not match. Check, too, that the user has been added to the database with all privileges.

If you are unsure of the password, set a new one for the database user in the control panel, then type it into wp-config.php between the single quote marks. Save the file and reload your site.

2. The database server is down or overloaded

If nothing changed on your side and the error appeared suddenly, the database server itself is the likely cause, and only your host can fix it. Tell their support when the error started and ask whether the database server is running. Leave wp-config.php alone meanwhile: if nobody changed the details, they are probably still correct.

3. A damaged database

When wp-admin says tables are unavailable and may need repairing, WordPress has a built-in repair tool. It stays off until you turn it on.

First, back up the database if you can, using your host's backup tool: MySQL's own manual warns that a repair can lose data in some circumstances. Then add this line, from WordPress's own documentation, to wp-config.php, above the line that says "That's all, stop editing!":

define( 'WP_ALLOW_REPAIR', true );

• Run the repair. Go to yoursite.com/wp-admin/maint/repair.php and choose Repair Database. WordPress then reports whether each table is okay, was repaired or could not be repaired.
• Delete the line as soon as you finish. The repair page works without logging in, because a damaged database often blocks logins, so anyone could run it while the line is there. WordPress shows the same reminder when the repair completes.

Know the tool's limits. WordPress tables on a current MySQL server are normally InnoDB tables, MySQL's default type, and the repair command the tool uses does not work on that type, so it may report that a table could not be repaired. That means restoring a backup or asking your host. If your hosting space is full, free some up before you repair: MySQL can mark a table as crashed when the disk fills during a repair.

4. Hosting resource limits or a traffic spike

A database server accepts only so many connections at once, and a host can also cap how many each account may use. When a sale, a mention in the news or a burst of automated traffic uses them all, new visitors get the error until the load drops. The telltale sign is an error that comes and goes at busy times.

Ask your host whether your account hit a connection or resource limit, and what plan or setting raises it. Page caching helps too: a caching plugin serves saved copies of your pages instead of running WordPress, and its database queries, for every visitor.

5. A full or hacked database

WordPress's documentation names two more possibilities. Your database may have reached its storage quota, in which case the host may have shut it down: ask them how much space it uses and what the limit is.

Or, if the details are correct and your host confirms the server is healthy, the site may have been hacked. Your host may be able to tell an actual hack from a loss of service. If it was hacked, change every password, including the database password (and the copy in wp-config.php), and restore a clean backup or have the site cleaned.

When should you restore a backup?

Restore a backup when the repair tool cannot fix the damage, when content is missing or scrambled, or when the site was hacked and you have a copy from before the hack. Ask your host first: if the server was the problem, a restore is unnecessary.

Restoring replaces your current database with the backup, so the site goes back to how it was on that day. On a store, orders and customer accounts created since then disappear, so note them first. A database backup also leaves out your files, wp-config.php among them, so make sure the restore covers both. If you can, copy the site as it is now, even broken, before restoring.

Should you call your host or a WordPress professional?

Call your host first when nothing changed on your side, when the error came out of nowhere or comes and goes, or when their status page shows a problem. Server outages, storage quotas, connection limits, database passwords and server backups are theirs to handle.

Call a WordPress professional when the host says the server is fine but the error remains, when the error started after a move and you would rather not edit wp-config.php, when the repair tool reports failures, or when you suspect a hack. If you need it fixed quickly, WP Resolve's Emergency Fix is a flat $199 with a 24-hour turnaround, and no plan is needed.

How can you stop it from happening again?

You cannot prevent every server outage, but you can make the next one shorter and less costly:

• Keep daily off-site backups and know how to restore them, so a damaged database is an inconvenience rather than a loss.
• Use uptime monitoring, so you hear about an outage before a customer does.
• Use page caching to reduce database load at busy times.
• Add a friendlier error page. If a file called db-error.php exists in the wp-content folder, WordPress shows it instead of the plain message. A developer can make one with your logo and phone number, so customers can still reach you.

WP Resolve's care plans include backups and monitoring: Essential Care, at $79 a month, includes daily off-site backups kept 30 days, malware scanning and uptime monitoring.

Not sure how your backups and hosting would hold up? Ask for a free site health check covering updates, backups, security and speed, or text (916) 209-0917.

Frequently asked questions