Did you just try to access your WordPress site only to be hit by a nasty message that reads “error establishing a database connection”?

You know – the one that looks something like this:

It’s definitely a frustrating error because it seems like your site has disappeared. But here’s the good news:

• Your site’s existing content should still be safe and sound – WordPress is just having trouble accessing it.
• There are some common steps you can take to get your site back up and running.

In this post, I’ll explain what’s causing the error and what it means. Then, I’ll take you through four different troubleshooting steps you can use to fix the error establishing a database connection message in WordPress.

What Does The Error Establishing A Database Connection Message Mean in WordPress?

In order to explain what causes the error, I have to give you a quick primer on how WordPress functions.

Your WordPress site has two main parts:

• The code that powers your site’s core functionality and determines how it looks.
• The database that actually stores your content. For example, every post or page that you write is stored in your site’s database.

This is a bit oversimplified*, but let’s say your website is like a book that’s ready to be printed:

• Your site’s code is like a printer. It has the sheets of paper and the ink – it just needs to know what to print.
• Your site’s database contains the actual words that the printer will put on the page.

Without both parts, there’s no book for people to read!

When your WordPress site can’t access its database to figure out what content to display on your site, it displays the error establishing a database connection message instead.

*your site’s database also stores lots of other important stuff – like settings, user data, etc.

What Causes The Error Establishing A Database Connection Message In WordPress?

There are several potential reasons why your WordPress site is unable to connect to its database. We’ll cover fixes for each below, but let’s start with a quick summary:

• A corrupted database – sometimes, your actual database can become corrupted for one reason or another, one core reason for that dreaded “error establishing a database connection” message.
• Incorrect database credentials – in order to connect, your WordPress site needs the database name and host, as well as the username and password of a valid database user. If any of this information is wrong, it will throw the error.
• Corrupted files – beyond a corrupted database, sometimes the actual files in your WordPress install can become corrupted and cause this issue.
• Database server issues – sometimes it’s nothing wrong with you or your site – your server might just be experiencing issues.

Below, I’ll show you how to diagnose and fix these four potential issues which cause the error establishing a database connection” message.

But first…

Always Back Up Your Site Before Making Changes

Because some of these fixes involve digging into sensitive areas of your site, you should always back up your site before making any of these tweaks.

Sure, your site may already be experiencing issues, but you never want to make things worse!

1. How To Fix A Corrupted Database

This issue isn’t necessarily the most likely cause of the error establishing a database connection message, but it is the easiest to diagnose, which is why I always like to rule it out first.

To see if your database is corrupted, try to access your site’s wp-admin dashboard. If you see the exact same error establishing a database connection message, you can safely rule out this issue and skip to the next section.

If, however, you see a message like “One or more database tables are unavailable. The database may need to be repaired“, then you likely have a corrupted database.

So:

• If you see the same message, skip to the next section.
• If you see a message about unavailable database tables that need to be repaired, follow the steps right below.

Step 1: Enable WordPress Database Repair Function

WordPress includes a built-in tool to help you repair a corrupted database. To enable it, you’ll need to add this short code snippet to the bottom of your wp-config.php file:

define('WP_ALLOW_REPAIR', true);

You can edit your site’s wp-config.php file by:

• Connecting to your site via FTP
• Using something like cPanel File Manager

Step 2: Run Database Repair Tool

Once you’ve added that snippet, you can run the database repair tool by going to:

www.yourwebsite.com/wp-admin/maint/repair.php

Click the button to Repair Database and WordPress will do the rest:

Step 3: Disable Database Repair Tool

If the repair process went well, your site should now be functioning normally. Now, just go back to your wp-config.php file and remove the code snippet you added in Step 1 to finish the process.

Or, if you’re still experiencing issues, skip ahead to the next potential fix!

2. How To Fix Incorrect Database Credentials

If you just installed or migrated WordPress, this is the most likely issue. And even if you didn’t, this problem can still crop up for some odd reasons.

While a lot of tutorials show you how to test if your database credentials are working, it actually takes less time to just create a new set of database credentials and use those. This way, you can be 100% certain you have the right details and save some time to boot!

Step 1: Verify That You Have The Right Database Name

To verify your database name, you can use phpMyAdmin, which is accessible from cPanel at most hosts:

Find the name of your current database by looking for the DB_NAME entry in your site’s wp-config.php file (you can view this file via FTP or cPanel File Manager):

Then, select that database name in phpMyAdmin and find the wp_options table (it could be more like wpXX_options, depending on your host’s settings):

Make sure you see your site’s URL in the siteurl field of the wp_options table:

If you have the right database name, the next step is to create a new set of credentials.

Step 2: Create New Database User Credentials

To create a new database username and password, go to the MySQL Databases option in cPanel (or the equivalent at your host):

Find the Add New User section and enter a username and password (keep these details handy because you’ll need them in the next step):

Then, scroll down to the Add User To Database section and select the user you just created and your site’s database name from the drop-downs:

On the next page, make sure to give the user All Privileges and save your changes:

Step 3: Update wp-config.php File

Now, edit your wp-config.php file and enter the username and password that you just created in the fields for:

• DB_USER
• DB_PASSWORD

Once you save your changes, you can be 100% certain that you have the proper database credentials and, hopefully, your site should start functioning normally again.

3. How To Fix Corrupted WordPress Core Files

If neither of the above methods has fixed the issue, you might have some corrupted core WordPress files. The easiest way to fix this issue is to just upload a fresh copy of the WordPress core – here’s how:

Step 1: Download A Fresh Copy Of WordPress

Head to WordPress.org and download the latest version of WordPress (or, if you’re running an older version for some reason – download that version):

Step 2: Delete wp-config-sample.php And wp-content Folder

Once you’ve downloaded the proper version, extract the ZIP file. Then, you should delete one file and one folder:

• wp-config-sample.php file
• wp-content folder

Deleting these files ensures that you don’t overwrite any important files. Speaking of…

Step 3: Upload And Overwrite Remaining Files

Once you’ve deleted the file and folder above, use FTP to upload the remaining files to the folder where your WordPress site is installed.

Your FTP program should ask you what to do with duplicate files. Make sure to select the option to Overwrite the files (here’s what that looks like in FileZilla):

Now, you can be sure your core files are clean and, hopefully, your site will start working again.

4. How To Fix Database Server Issues

If nothing has fixed the issue so far, one more potential cause is issues with your database server.

This could be because:

• Your database server is overloaded (common with budget shared hosts experiencing heavy traffic).
• Your host is experiencing issues unrelated to your site’s usage (less common, but can happen).

It’s difficult to diagnose these two issues yourself, so your best bet for this one is to talk to your host’s support. They should be able to tell you:

• If one of these two issues is the cause
• How you might be able to fix it

If your database server is overloaded because of your site’s usage, one easy way to lessen the load on your database server is to make sure that you’re using a solid caching plugin, so you can avoid the error establishing a database connection message.

Still Experiencing Issues?

We know issues like this are frustrating. That’s why we created GoWP – to give you the support you need so that you can focus on the fun parts of running a WordPress site.

If you still can’t fix the error establishing a database connection and want a helping hand, get in touch.