Most of the time WordPress runs like a well-oiled machine – causing very few problems. Every now and then, something strange happens. Sending you on a wild goose chase, desperate to figure out the cause of the problem and get you 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 all contained within your database.
That’s why there is one message that sends fear into the hearts of every website owner. Its 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 the idea of 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 been doing so, today is the day that 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.
Either way, as we get into the troubleshooting part of this post, it’s important to make sure you’ve created a fresh backup before you make any changes to your MySQL database or click 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. To put it simply, 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. In order 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, if a visitor arrives on your homepage, 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 every now and then, something goes wrong. WordPress goes looking for information and – nothing. Silence. For whatever reason, WordPress is unable to 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, as with most things in WordPress, 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 login to your cPanel and open up your file manager, selecting “Web Root (public_html/www)” and then clicking “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.
In case 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 you’re 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 the 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. From there, 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 at this point in time.
Once this step is complete, go back to your file editor, delete the line that 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 using the drop-down box as shown below, select “Repair table”.
Once this action shows as being successfully completed, you can close phpMyAdmin and test your website.
There Is a Problem With the Server
The third and final possibility is that your error message is actually being caused by a problem with your server. If your website is hosted in a shared environment it is usually more likely that the problem is caused by an overloaded server.
With many shared hosting companies, there can be thousands of other websites 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 pretty 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.
In the event that this problem happens more than 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 about how to fix it or you 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.
In almost all cases, even with shared hosting, you’ll find that customer support is more than happy to help you resolve this error. 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.