Fixing the WordPress “Establishing a Database Connection” Error
Published by Drew Hendricks • Resources • Posted October 18, 2018
ContentPowered.com
One of the most infuriating things about dealing with software, coding, and development is error messages. Almost no one in the history of the world has been able to write a piece of software with graceful failure states and verbose error messages that tell you exactly what the problem is.
There’s a real reason for this, of course. The average user doesn’t know enough to fix whatever an error is. If an error message gives a lot of information, they’re more likely to misconstrue it or ignore it. Some will even try to fix it and, in their ignorance, break more than they fix. Meanwhile, developers who know what they’re doing can look for more information in log files and error codes, taking a generic error and turning it into a specific set of steps to fix an underlying problem.
The stereotypical Windows blue screen of death was always one such error. To many, a blue screen is a blue screen. To those in the know, the hex error code points to a specific problem. Even still, the pointer might be inaccurate. Here’s a story: Once, I had a PC where the processor was going bad. Each time the processor errored, the computer blue screened, and the blue screen hex code pointed at whatever was in use by the processor at that exact moment. Essentially, the processor threw up its hands and went “it wasn’t me, it was… THEM!” randomly every time. It took a long time to diagnose the underlying cause, including replacing many other parts that were perfectly fine.
All of this is a digression simply to say that some error codes are easier than others to understand. On one end, you have nice, clear error codes. On the other end, you have errors like the blue screen. Unfortunately, the WordPress “Error Establishing a Database Connection” is one of the latter. There are a lot of different potential causes, and there’s no real way to tell which is which without going through them and testing to see if a given solution is available.
Thus, let’s go through various possible solutions and see if we can help you figure out what’s wrong with your specific instance.
Behind the Error
The first requirement to understanding any error code is understanding what can cause the error. In the case of the database connection – one of Sherlock Holmes’s least interesting stories – it means understanding how WordPress works and how this error can appear.
WordPress is a framework that uses PHP and MySQL to create a website. The PHP – a programming language – is used in template files to pull specific elements of data from a database or generate other elements on its own. The database it pulls data from is set up in MySQL.
Your database sits on your server and holds your website content, both static elements and dynamic elements. Everything from your blog post content to your site title to your color settings are stored in the database. You can see your database settings in your wp-config.php file.
When a user visits your site, your server gives them the PHP files they need to render your site. Those PHP files, while rendering the page, need to connect to the database to get data necessary for rendering the site. If, for some reason, they cannot connect to your database, you get the Error Establishing a Database Connection.
This has a few implications, but one of them is actually quite good for you. The error is in establishing a connection to the database, not in the database itself. Usually this error simply means a configuration issue or a code conflict, and not an error with the site itself. You don’t usually have to worry about your site disappearing entirely.
In most cases, this means that your database credentials are incorrect, or that you haven’t given your database user full permissions to access your database in your cPanel.
Now, of course, if your database is deleted entirely, you won’t be able to connect to it, and this error will pop up. That’s a worst-case scenario, though, so don’t worry too much about it. Chances are very good your problem comes from somewhere else in the chain. Let’s look at those possible causes.
Hosting Issues
There are three kinds of issues that could come up with your web host that can cause the error connecting to your database.
The first is actually downtime with your web host. Many web hosts promise 99.999% uptime, to a certain number of digits out, but 99 is not 100. Even the best web host can have a catastrophic issue and go down. Maybe it’s an entire data center, or maybe it’s just an issue with the single server hosting your website. If you’re on shared hosting – which a lot of smaller sites are, because it’s cheaper – another customer on the same server might be hogging the bandwidth or server resources and crowding out your site.
It’s worthwhile to check with your web provider to see if they notice any errors. They can tell you if the problem is on their end, and they can often help you troubleshoot through several other common causes. Figure out where your web host support is, and see if you can establish a live chat or an email/phone support ticket. Live chat is the best, since you can work directly with a support agent without needing to relay instructions tediously over voice.
If the web host is having issues, they can likely solve the problem relatively quickly, depending on the scale of the problem. Either way, what you’re looking to do is confirm whether or not the error is on their end. There’s nothing worse than struggling to troubleshoot a problem for hours only to find it wasn’t something you could fix in the first place.
I said there are three kinds of issue with web hosting, but I’ve only talked about one. The other two are variations of a DDoS.
A DDoS attack is pretty simple. Basically, imagine any business, with a handful of doors at the front to let people in and out. Now think of Black Friday, how crowds make it slow and difficult to get in or out of the building. If the store is your web server, and the customers are your visitors, that’s the basis of a DDoS attack. Too many people trying to use too limited resources to access your site.
A bad DDoS attack involves an outside agent using a botnet to create thousands of artificial people to clog the doorways. A “friendly” DDoS attack is what happens when your site goes viral and gets 100x its normal traffic, making it impossible for people to access the site simply because too many people are trying to access the site at once. Reddit calls this the “hug of death”. It’s a “good” problem to have, in that you like going viral and you like the traffic and interest, but if it brings down your site, it’s still not good.
On shared hosting, someone else on your web server could be the target of a DDoS attack of either sort and is bringing down your site from the collateral damage. To use the storefront analogy, it’s like if all the entrances to a shopping mall are clogged up because of a great sale at the Build-A-Bear Workshop inside. The other stores are crowded out because they’re in the mall too.
A DDoS isn’t something you can just stop or fix, but you can take some steps to make your site harder to take down. It’s a lot, so I’m not going into it here, but you can read up on it elsewhere.
Authentication Issues
Once you have eliminated hosting issues as potential causes, you can look at issues you may have caused. Here are a few possibilities.
The first and one of the most likely issues is an authentication issue involving adding a new user. When you add a new database and a new user, you should first check the wp-config.php file. This file should have the login information necessary to access the database. Your file should have the DB_NAME, DB_USER, DB_PASSWORD, and DB_HOST all defined. More importantly, they need to be correct for the name of the database, the username of the user accessing the database, the password needed to authenticate, and the host (or localhost) for the database. Make sure all of these are correct, because if any of them is incorrect or has a typo, you’ll see your database connection error.
Another fairly likely issue is related to that. You added a new database and a new user, and your details are correct in the wp-config.php file. What now? Well, check your cPanel database management section. It’s possible that you failed to give the new user permissions to actually access the database. You will need to use cPanel to manage new users or new databases, and make sure the users are given appropriate access with to the database.
Another issue that’s somewhat related to authentication, but not quite, is an access issue caused by a firewall. In particular, Modsecurity absolutely loves to block admins from WordPress because they tend to access it frequently or making a lot of requests.
To fix this problem, find the firewall settings you’re using and make sure you’ve whitelisted yourself or your admins. It’s a fairly simple fix, but it’s one of those causes that can be really hard to figure out because other people see the site working fine.
Conflict Issues
If your authentication checks out and you can’t find any problems with users or passwords, you should check if any of your plugins were added or updated when this issue started. The same goes for your theme files, which I’m considering a sort of plugin for the purposes of this section.
Basically, you can find conflicts with plugins or themes. Since all of your plugin and theme files are PHP code, sometimes that code can be buggy in a way that works in isolation, but not in conjunction with other plugins or theme files. Incidentally, there’s a bit of overlap here with the next section, on corrupted files; you can use some of the same troubleshooting to fix issues there as well.
Log into your server and find the wp-content folder. In that folder, you should find folders with names like “plugins”, “themes”, and “uploads”.
Start by renaming the plugins folder. Just add a simple 1 or _ to the end of the folder, so “plugins” becomes “plugins_”.
Since WordPress is looking for the “plugins” folder, it won’t find it, and will assume there are no plugins. It will then work as if you have no plugins installed. Check your site. Does it work? If so, one of your plugins is causing the issue. If not, restore the name of the plugins folder and change the name of the themes folder. Does it work now? If so, your theme is borked. If not, you have other issues, and should move on to the next section.
Once you have the issue narrowed down to either plugins or themes, go into the folder and look at individual folders for specific plugins or themes. Start doing the rename trick and removing individual plugins to test. Keep checking until you find the one that you deactivate that makes your site work.
When testing themes, it’s easier to go into your WordPress admin dashboard and change the theme for your site. Start with the default theme; if it works, you know your custom theme is messed up. Try reinstalling the theme, or getting your developer to work on it if the theme was custom-made for your site.
Corruption Issues
Finally, we have the file issues. You can have two sources of corruption here; files or databases. Files is a better problem to have.
Go to WordPress.org and download a new copy of WordPress, and unzip it locally. Find the wp-admin and wp-includes folders. Also, find the other root files except for wp-config.php.
Go to your server and back up all your existing data. You don’t want to do a restore and find you made things worse with no recourse, after all. Once you have the backup, take your new versions of the wp-admin, wp-includes, and root files and copy them over. If any of those files were corrupted, WordPress would have stopped working, and replacing the files should fix it.
If everything above has failed to work, it’s time to look for the worst case scenario. It’s possible that your MySQL installation, your PHPMyAdmin installation, or your database itself is corrupted. You may need to reboot the server – something your web host can help with – or you may need to restore from a backup. Something broke, and these kinds of errors are often unfixable. You need to restore data, which you hopefully have. Always keep good backups, friends!
Drew Hendricks is the CMO of Blogpros and a contributing writer to Inc., Entrepreneur and Success.
