How to Solve WordPress Database Error
The longer you work with WordPress, the more likely you are to come across the dreaded ‘error establishing a database connection‘. This is a scary one, because you’ll likely be able to access, in part, either the front or back end of your website — and, if you haven’t yet gotten your head around a few fundamental concepts about servers and/or web development, you’ll probably be at a loss.
Here’s how to go about understanding and troubleshooting this unnerving error.
What Does ‘Error Establishing a Database Connection’ Actually Mean?
Instead of being saved in specific files, the content of WordPress posts and pages is saved in a database that WordPress needs to reference each time it serves/generates a webpage. When a post gets viewed, for example, WordPress finds the database host, connects to its database, finds the WordPress posts table within that database, and looks up the content it’s trying to load. In short, the infamous ‘error establishing a database connection‘ means that WordPress cannot find this database.
Why is this such a big issue? Well, in addition to the content of posts and pages, WordPress also stores a whole heap of other essential information in its database — such as its main settings, your user data, your selected theme, your widget settings, data for your active plugins, and so on. If WordPress can’t access any of the information within its database, it has no way of loading your website.
What Is the Cause of a Database Connection Issue?
There are a number of issues that could cause a communication problem with the database. Let’s create a shortlist, and delve deeper to better understand (and solve) each problem:
- Incorrect database credentials (username, password, host, database)
- Corrupted files
- Corrupted database
- Database server is overloaded or malfunctioning
But first…
While the processes I’ll be looking at aren’t dangerous, it’s always a good idea to have a backup — just in case. If you’re already using a tool such as VaultPress — which I heartily recommend — you’re already backed up and good to go.
There are lots of plugins that can back things up for you, but if you’re already locked out of WordPress you won’t be able to use them. In this case, you’ll need to use your cPanel or other hosting management software to make a complete backup.
If you don’t know how to do this, talk to your hosts — most of them will have a backup solution of sorts. Be sure to back up your database, as well as the files on your server, since it’s the database that contains all the critical information for your website.
Fixing Database Connection Issues
I’ve written the above list in order of likelihood, based on my experience, but you can start from the bottom and work up if you prefer. That said, if you don’t have a direct line (or chat support) with your host, it will be difficult to tell whether or not a database server is overloaded or malfunctioning on their end, because from your end the symptoms are indistinguishable. In any case, let’s take a look at each of the causes and see what we can do to fix things.
INCORRECT DATABASE CREDENTIALS
This is one I see quite often. If you see the ‘error establishing a database connection’ message when setting up a brand new WordPress install, then this is almost certainly the culprit. To connect to its database, WordPress needs four key pieces of information:
- Database host
- Database username
- Database password
- Database used
All this information should be given to you (if not actually entered on your behalf) by your host. However, if you’re using a more flexible setup (i.e. not a one-click type of install), you should check your username, password, and the name of your database. Your best bet is to copy and paste all the data directly from the medium in which it was given to you. (Note: Passwords can sometimes have dashes or periods at the end that aren’t normally selected.)
If you’ve recently switched hosts, make sure to double-check the ‘database host’ details. In many cases, this will be ‘localhost’ (Bluehost, HostGator). It should be noted that many hosts use an IP Address (SiteGround) or even a completely different URL (DreamHost). If you’re unsure about any part of this you should either contact your host and ask them directly or look at their online knowledgebase (if they have one).
On a new install, you’ll likely be presented with fields in which to enter this information as you go through the standard WordPress on-screen setup routine. In many cases, you can even go back and fill out this information again. If not, you’ll need to download, edit and then (using an appropriate FTP client) re-upload the configuration file located in the WordPress root directory (called).
wp-config.phpBe sure to only edit this file using a text editor, of course. The database connection details are near the top, and look something like this:
define('DB_NAME', 'database_name');
/** MySQL database username /
define('DB_USER', 'database_user');
/* MySQL database password /
define('DB_PASSWORD', 'database_password');
/* MySQL hostname */
define('DB_HOST', 'database_host');Simply change the values in the second set of parentheses to modify your connection details to the correct values, and you should be up and running in no time. If, however, you’ve checked and double-checked all of these details, and you’re still getting the same error, then it’s time to move on to the next issue: Corrupted files.
CORRUPTED FILES
In some cases, users have reported that re-uploading the core WordPress files sometimes fixes the error — the exact reason why this can work may seem like a mystery, but, in many cases it’s to do with either resetting file permissions or replacing corrupt core files. (Note: Be sure not to overwrite either the config.php file, which contains crucial setup information, or the
wp-contentdirectory, which holds your themes, plugins and media, and remember to always back up before modifying or replacing anything.)
To get this done, you’ll need to download a fresh version of WordPress fromWordPress.org and unzip the package on your computer. Go into the unzipped folder, and delete both the config.php file and the wp-content folder to be sure you don’t accidentally replace the ones on your live server. Once these have been deleted, open an FTP client and prepare to upload the remaining files to your WordPress root folder.
Assuming nobody’s ever made dodgy modifications to your WordPress core files, you should now be able to safely overwrite all of these files on your live server — making sure not to accidentally overwrite the wp-config.php file or the wp-content folder, of course.
CORRUPTED DATABASE
A good indication of a corrupted database is if the website front end works, but the backend doesn’t (or vice-versa). You may also see an error message telling you that some database tables cannot be found. Luckily, WordPress contains a tool that can help you repair a corrupted database. You’ll need to download your
wp-config.phpfile (which you’ll find in the root directory of your WordPress install) and add the following line:
define( 'WP_ALLOW_REPAIR', true );
Once you’ve re-uploaded it, you should be able to access a special database repair page on your site by going to
http://yoursite.com/wp-admin/maint/repair.php(substitute yoursite.com with your actual domain). You should see a screen displaying two options: ‘Repair Database’ and ‘Repair + Optimize Database’.
Although choosing either option should be fine, I’d recommend choosing only to repair the database. As a programmer, I’ve learned that even the seemingly irrelevant can cause unpredictable issues. I don’t see how also performing an optimization could ruin things, but it’s better to be safe than sorry in these situations. At the very least, optimizing the database as well as trying to repair it will almost certainly take quite a bit longer — and getting the database up and running should be the priority.
Once this has been done, be sure to go back into
wp-admin.phpand remove the above-mentioned line of code from the file. The repair page is not hidden and is not secure; it will remain publicly accessible for as long as that piece of code exists in the config file.
DATABASE SERVER IS OVERLOADED OR MALFUNCTIONING
Malfunctioning and overloaded servers are very difficult to differentiate without either having access to advanced hosting tools or talking to your hosting company. If you suspect one of these is happening and your host has real-time telephone or chat support, then your best bet is to ask them what’s going on directly.
If you’re using a shared server (meaning you have to share the server’s resources with a large number of other people), it can be hard to tell whether the cause of the error is because of an overload or a malfunction. In some cases, instead of a malfunction, it may actually be because another site on the same server is overloading the database. In other words, even if you have only a very small site with no sudden surges in traffic, it could be experiencing an overload caused by someone else’s website. This is a lot less likely to happen with a VPS or a managed WordPress hosting setup. The good news is that both these issues usually resolve themselves within a relatively short time. If a database physically malfunctions, your webhost will almost always move to replace it as soon as their systems indicate the need to do so — and if a database goes down because of an overload, it will usually automatically reboot and be up and running again within a matter of minutes. If, however, this has happened a number of times, alert your hosts and have them investigate as soon as possible.
If your website is on a shared server and your traffic is rapidly increasing, you may start to experience database connection issues as you start to overload the server. Such errors will usually resolve themselves, but will happen again if your website continues to experience surges in traffic. In such cases, if you aren’t already doing so, using a good caching plugin, such as W3 Total Cache, WP Super Cache or WP Rocket may well alleviate further issues.
That said, the easiest way to solve this issue is to prevent it from happening at all.
Managed WordPress Hosting
While not a solution per se, moving over to a managed WordPress hosting package could save you a lot of headaches if you’re already starting to see these types of errors. Managed WordPress hosting is less flexible from a features point of view, but, if all you need is to be able to run WordPress, it can be an excellent option. (This very site runs on such a service.) WordPress-specific managed hosting is tailored to running WordPress as efficiently and quickly as possible. The hardware, the server software, and the customer care representatives –just about everything, in fact — are geared towards (and optimized for) WordPress!
The downsides of this type of hosting are not being able to access your server via SSH, and not being able to install other scripts outside WordPress (i.e. you can run WordPress and nothing else). Additionally, most managed WordPress hosts will prohibit you from using certain plugins that have been deemed either substandard and/or unsuitable for their systems.
If you’re interested in managed WordPress hosting, take a look at the options. Some of the best are those offered by WPEngine (arguably the leader in the managed WordPress hosting arena), Pagely (great for large businesses) and Flywheel (geared towards designers and agencies).
Overview
As you can see, the exact cause of the infamous WordPress ‘error establishing a database connection’ can be one of many. In my experience, however, in the vast majority of cases it’s either because of some kind of user-generated error (e.g. a typo in the config.php file) or is an issue that can be resolved by the user. If you’re having trouble, follow the methods outlined above to get your site up and running — and, if you’re still having no luck after that, talk to your host to have them look into the problem for you.
If you’ve seen any edge cases or downright weird things happening in relation to this error, let us know in the comments below.