WordPress often runs like a well-oiled machine – causing very few problems. Now and then, something strange happens. Sending you on a wild goose chase, desperate to figure out the cause of the problem and get your website back up and running.
Almost everyone understands the importance of the WordPress database. It contains everything that makes your website unique. Your content, images, meta descriptions, settings, user information, and more are within your database.
That’s why there is one message that sends fear into the hearts of every website owner. It’s the plain white screen with the ominous phrase across the top stating “Error establishing a database connection“.
Before you stop, drop and roll in a state of panic, take a deep breath and realize that we can usually fix this problem in just a few minutes. That’s exactly what we’re going to run through today.
First Things First: A Backup Primer
We’ll keep this short and sweet. There are always a few people out there who still haven’t jumped on board with creating regular backups.
Of course, this wouldn’t be you, would it?
If it is, the error establishing a database connection message is usually the ideal wake-up call. The thought that the database could have a sudden problem usually scares people into the habit of creating regular backups.
So, if you haven’t already done so, today is the day you’ll start creating regular backups of your WordPress site. Once we get your database back up and running, you can head over to this article to check out an easy way to get started.
As we get into the troubleshooting part of this post, it’s important to ensure you’ve created a fresh backup before making any changes to your MySQL database or clicking on anything in phpMyAdmin. By “fresh backup”, I mean a completely new version. Don’t overwrite something that was created before the error message was generated.
What Does Error Establishing Database Connection Mean?
The heart of any WordPress website is the database. MySQL is the open-source database responsible for storing virtually all of the critical information required by your website. Simply put, without a database, you’ve got nothing but a blank white screen.
Anytime a visitor comes to your website, WordPress, which is built on PHP, is required to deliver the requested page to your visitor’s browser. To achieve this, WordPress communicates with your MySQL database and requests the required information. This includes absolutely everything that the end-user sees on their screen.
So, suppose a visitor arrives on your homepage. In that case, WordPress will request from the database information that includes your current theme, the header and logo, any images or text, sidebar widgets, settings, footer content, and more. It’s a long list.
But now and then, something goes wrong. WordPress goes looking for information and – nothing. Silence. For whatever reason, WordPress cannot connect or pull the required information from your database. When this happens it returns a blank white page and an error message “Error establishing a database connection“.
Once this happens, it’s up to you or your hosting company to find the root cause of the problem and fix the error.
Why Does This Error Happen?
It would be nice if the cause of the error was as clear as the error message itself. Unfortunately, that’s rarely the case. Most of the time the problem can be resolved quickly with just a little digging. Other times, you may need to escalate the situation by getting in touch with your hosting company. As you’re working through these problems and solutions, remember that, with most WordPress things, there are usually multiple ways of solving the same problem.
Let’s take a look at the three most common reasons:
Your Database Credentials Are Incorrect
If you’ve recently installed WordPress through your hosting company’s one-click installer, then chances are this is not the cause of your problem.
On the other hand, if you’re in the process of doing one of the following, then there is a good chance that this is where your problem resides:
- Installing WordPress using the “Famous 5-Minute Install“.
- Moving from a local installation to a server.
- If you are changing hosts or domain names.
Most of the time you’ll know whether there is a chance that your credentials are incorrect. If you’ve been entering or changing database credentials, it’s not something you do unknowingly.
Step #1 – Gather the Required Information
The first step towards resolving the error message is to gather all the required information. This includes:
- Database name
- Database host (usually but not always “localhost”)
- Database username
- Database password
This information can be found in your cPanel under MySQL Databases (pictured above). Opening up this window will display a list of Database installations as well as a list of database users. Keep this window open while you move to step number two.
Step #2 – Cross-Check Your Database Credentials
Your second step is to download or open up your wp-config.php file. You can do this using a basic FTP program such as FileZilla but it’s easier to log in to your cPanel and open up your file manager, selecting “WebRoot (public_html/www)” and then click “Go”.
Next, select the wp-config.php file (as seen above), and at the top of your screen click “Edit”. This will open up the file and enable the editor. Scrolling down a few lines you find the information that you are looking for:
All of the information contained within quotes, for example, ‘database_name’, must match exactly with your actual database credentials. Even an extra space after the quotes can cause an error message.
If you’re wondering what your database host should be set to, you can either check with your hosting company’s support team or this list.
If unsure of your password, you can simply select the user (as seen in the image below) and reset the password. Then copy and paste the new password into your wp-config.php file.
If for any reason, you’d rather start from scratch. You can simply create a new user and assign them to the database. Just make sure that if you have multiple database installations, you apply the new user to the correct database (you may only have one).
Step #3 – Check Your Table Prefix
While you’re looking around your wp_config.php file it’s also a good idea to make sure your table prefix is correct. If you’re referencing the wrong database, it won’t matter how accurate your login details are. Look for the following text:
Often your table prefix will say ‘wp_’, but it can be set to anything for example ‘wp63ts7_’
Make sure your actual table prefix matches what’s in your wp-config.php file.
Your Database Is Corrupt
If you’ve gone through all of the steps above to no avail, double-checking closely for any typos or missing information, the next possibility is that your database is corrupt.
A tell-tale sign of database corruption is when the front-end of your website seems to be working properly, but the back-end displays the error message or vice versa.
If this is the case, you’re probably on the right track. This potential fix is a little less tedious than checking all your database credentials, but it still requires a little work. There are two potential ways to get the job done:
Option #1 Enable the WordPress Database Repair
Following step #2 above, you’ll want to open up your wp-config.php file using the editor.
Scroll to the bottom of the file and add the following line of code:
define( 'WP_ALLOW_REPAIR', true );
Save your changes, but keep the editor open, you’re going to need it in a few minutes.
Next, open up a new tab in your browser. Navigate to the following URL:
This will open up the WordPress database tool that will look like the image below. You can select either “Repair Database” or “Repair and Optimize Database”. However, to stay on the side of caution, it might be best to simply repair the database.
Once this step is complete, go back to your file editor, delete the line you added at the bottom and save the file again. You have now disabled the repair tool. Don’t forget this final step.
Option #2 Repair Your Database Using phpMyAdmin
Another way to repair your database tables is through the phpMyAdmin interface in your cPanel. Although quicker and easier, this method also requires a little more caution since you can completely wipe out your database from within phpMyAdmin.
Friendly reminder: Always backup your database before making any changes.
Once you’ve opened up phpMyAdmin (see above), select the appropriate database on the left side of your screen. Next, make sure the structure tab is selected. Then, highlight all the tables and use the drop-down box, select “Repair table” below.
Once this action shows as being completed, you can close phpMyAdmin and test your website.
There Is a Problem With the Server
The third and final possibility is that a problem with your server is causing your error message. If your website is hosted in a shared environment it is usually more likely that an overloaded server causes the problem.
With many shared hosting companies, thousands of other websites can be hosted on the same server. If one of those users decides to abuse the server resources, whether intentionality or not, it’s possible that their actions can affect everyone else whose website is hosted on the same server.
The good news about this scenario is that users causing this type of problem are usually red-flagged quickly. Once your hosting company discovers the problem, the offending account is suspended or put on a very short leash.
It’s also possible that these problems are not caused intentionally. If your website or another website on the same server is featured in the press or the front page of Reddit for example, a sudden traffic spike can overload the database. This type of problem will also tend to self-resolve fairly quickly. If you’ve tried everything else and your site is still offline after a few minutes, it could be time to call or chat online with your hosting company.
If this problem happens occasionally and is a result of using shared hosting, you might want to consider switching to managed hosting instead. While it’s a little more expensive, you’ll rarely have these kinds of problems to deal with.
That pretty much covers the three most common reasons that you might experience the “Error establishing a database connection” message:
- Incorrect database credentials.
- A corrupt database or individual database table.
- A problem with the server.
In most cases, this error message is a problem that can be resolved in under 15 minutes. If you’re unsure how to fix it or are uncomfortable with the methods covered in this post, it’s probably better to contact your hosting company or turn to a WordPress support service. The last thing you want to do is cause more damage to your database.
Even with shared hosting, you’ll find that customer support is more than happy to help you resolve this error in almost all cases. If not, it might be time to look for a different hosting company.
If you’ve ever experienced problems with your WordPress database, please share in the comments below.