How to Fix the “Establishing a Database Connection” Error in WordPress

As a WordPress user, you must have seen the “Error establishing a database connection at least once. Along with the notorious white screen of death (or Error 500), this is one of the most common errors you could encounter on the internet. 

In this post we break down some simple troubleshooting steps to help you fix this error.

Contents

“Error Establishing a Database Connection” – What Does it Actually Mean?

The MySQL database contains all of the information from your WordPress site. This includes meta-information, as well as plugin settings, post and page data, and the likes. The only type of data that’s not being stored in MySQL is media content (images), and also your site’s theme/plugin/core files (for example, index.php, wp-login.php). 

Once your site is being hit by a visitor, the code your page (and hence your entire site) has been written in, will be executed by PHP. PHP will also do a database query, meaning it will request data information from your site’s database table, and that, in the end, will show up as your website in the visitor’s browser. 

But, some sort of setback can always occur. Sometimes things go wrong and all this process explained above simply won’t work as it should. In these cases, what you or your visitors end up seeing is the “Error establishing a database connection” message. 

This error is annoying both because it shows up in the visitor’s browser, but also because it won’t let you get to your dashboard in WordPress. The good news is, though, that not all visitors can see the “Error establishing a database connection” message immediately. 

If your site is still serving cache then your site might linger online for a little bit more. Which is a good thing, since it can buy you time to fix it! And don’t worry, it won’t take you as much time as you think – it’s totally doable under 15-20 minutes! 

So, How Does it Actually Happen? 

How does the “Error establishing a database connection” error actually occur? 

Well, there are a few common reasons. After we go over them, we’ll proceed with what you can do in these scenarios to fix it. 

Incorrect Database Login Credentials 

This is arguably the most common reason behind the “Error establishing a database connection” message. If this is the reason behind the error message you’re seeing, then you will have to use different login information for your site so it can connect to the MySQL database. 

Corrupted Database 

Your WordPress site is a place of constant movement: it welcomes and sends off numerous plugins and themes, sometimes in a very short period of time, it constantly receives updates and so on, which is part of the reason why databases sometimes become corrupted. Sometimes a file can be missing or only one file can be corrupted. Data or information can also sometimes be deleted by accident. Another reason behind corrupted data can be hackers, and, of course, data corruption can also be present in your WordPress installation from the very start. 

Database Server Issues 

Sometimes it’s the host’s fault when it comes to error messages such as the “Error establishing a database connection” one. Again, there are numerous reasons why this is happening on the servers of your host. Often the database can become overloaded with traffic and go through a traffic spike; it can also become unresponsive if it’s being subjected to too many connections. If you’re on a shared host, then this is considered a very common issue, for the simple reason that shared hosts use identical resources on the same servers, for a bunch of different users. 

Okay, so now that you know the main reasons behind the “Error establishing a database connection” message, we can start getting our hands dirty with ways to fix it. 

But, before we tell you how to do it, one small, but very important reminder: do a backup. 

Why Should You Do a Backup? 

The nature of the “Error establishing a database connection” along with its tips on how to fix it requires a large amount of tinkering with the database information of your site. And, as you may have guessed by now, this is not something to fool around with or take lightly. 

Your database is your site, and if fixing a particular error requires you to do something with the database, then you definitely don’t want to make it worse. Hence the backup. Always, always do a backup when you set out to fix whatever it is you want to fix on your WordPress site. And this goes for experienced developers and IT guys and gals as well! 

A great backup tool you can use for these instances is BlogVault, which is the plugin we use and one that we heartily recommend! It has really important features for backing up your site, such as: 

  • Realtime backup capability (changes on your site are being backed up as they happen);
  • Superb system for informing you of its actions and telling you what it’s not backing up.

Overall, it’s an extremely reliable plugin that will tell you immediately when it’s not able to do a backup or has some sort of issues. 

Another option is to do a manual backup of your own MySQL database if you opt to use phpMyAdmin. A third option is to do a backup restore to staging or production. 

So don’t hesitate, always do a backup! And now, once we’ve got this covered, we can start with the actual steps and tips on how to fix the “Error Establishing a Database Connection”.

How to Fix the “Error Establishing a Database Connection”

1. Check Your Database Login Credentials

First thing’s first: check whether the database login credentials of your site are indeed correct. If you remember, we mentioned above that this is the most common reason behind this error (oftentimes it has to do with people migrating to another hosting provider). 

Your site’s connection details are placed in the wp-config.php file that’s usually found at the very root of your WordPress site. This file has four chunks of information which must be correct because otherwise, it’d be impossible to set a proper connection. 

The files are the following: 

  • Database Name

// ** MySQL settings ** //

/** The name of the database for WordPress */

define(‘DB_NAME’, ‘xxxxxx’);

  • MySQL database username

/** MySQL database username */

define(‘DB_USER’, ‘xxxxxx’);

  • MySQL database password

/** MySQL database password */

define(‘DB_PASSWORD’, ‘xxxxxxxxx’);

  • MySQL hostname (server)

/** MySQL hostname */

define(‘DB_HOST’, ‘localhost’);

The way to this wp-config.php file is through SFTP – you can connect through SFTP and reach your site’s root. Another option is cPanel (for those who prefer it) – where you have to find “File Manager” and then from there reach the root of your site. Once you’re there, simply do a right-click and edit the file.

Next, you should check the current values of your site and compare them with the ones on your server, to see if they match up. 

Check Database Credentials in cPanel

  • First, check the name of the database. You can do this by logging in to phpMyAdmin in cPanel – section Databases.
  • The left bottom side gives you the database name. If you see the “information_schema”, pass it by, since it’s info necessary for the host, and not for you in this instance. 
  • What you need to do next is to compare the database name you’ve located with the DB_NAME value in your wp-config.php file. If they’re the same, then the problem lies somewhere else. If, however, they’re not identical, then it means that you’ll have to do an update of your wp-config.php file.

Another way to make sure that you’ve found the right database is to look for the URL of your site contained within it. 

This can be done by:

  • Opening the database file and then clicking on the wp_options table (you also might encounter something like wpxx_options, since sometimes the table can be named differently because of extra protection). 
  • You should then be able to see name and URL values for your site at the top of the table. If they’re the same with your site, then it means you’ve hit the spot. 

But, what if you still see the database connection error even if you’ve found the database name to be correct? 

Well, then you have to move on to check the password and username of your site. What you need to do is to go to the root directory of your site and make a new PHP file. You’re free to name the file anyhow, you just have to keep the .php extension (for example, let’s say you name it dbtest.php). After that, you’ll have to put this code: 

<?php

$test = mysqli_connect(‘localhost’, ‘db_user’, ‘db_password’);

if (!$test) {

die(‘MySQL Error: ‘ . mysqli_error());

}

echo ‘Database connection is working properly!’;

mysqli_close($testConnection);

NOTE: What you see here as ‘db_user’ and ‘db_password’ is only for displaying purposes. When you go to your own root directory and your own file, you’ll need to put the values that are present in your wp-config.php file.

Then browse to the file on your WordPress site: https://____.com/dbtest.php. If you get the following: “MySQL Error: Access denied”, then it’s certain that there’s a problem with your password and/or username, which means you’ll have to reset them. 

NOTE: Don’t forget to remove the file once you’re done with the test. 

Change the Database Credentials in cPanel

  • In cPanel, go to the Databases section and click on the MySQL Databases. 
  • Then you will need to create a new MySQL user. 
  • Choose your new password and username and then click on the “Create User” option.
  • What you can also do is change the password on the particular screen for the current database user. 
  • After that you can add the new user to your database. When you see the question that will ask you which privileges you want to assign, you will need to press the option “All Privileges.” 

After this you should update your wp-config.php file with the new password and username. Update the DB_PASSWORD and DB_USER values. This should resolve the database connection error, if the problem was with the credentials. But, if you still see it, then it might have something to do with the hostname (for example, the hostname might be wrong, since certain hosts tend to use different values). Here is a list of common values hosts use, you can check it out to see if something matches. Reach out to your hosting provider for more details, and also if you’re not sure about the hostname. 

If you still see the database error after all this, then make sure to check out the next section on corrupt files and see if that might help. 

Fixing Corrupt Files

Corrupt files is another fairly common reason why you might see the database connection error. Files can get corrupted for various reasons: it might have to do with hosting issues, a hacker attack, or something that has gone wrong during the FTP file transfers. 

Even though this is something that’s totally fixable, it’s still highly recommended that you do a site backup before you set out to do it. 

The themes, plugins, as well as the media, won’t be affected; what’s going to be replaced on your site will be the core WordPress version (aka the installation). This is quite easy to do since it only requires you to go to WordPress.org and download the newest WordPress version.

After the download, you’ll have to unzip the file. Once you locate the ‘wp-content’ folder, delete it, along with the ‘wp-config-sample.php’ file.

You can upload the rest of the files on your site through SFTP. This will overwrite the ones already in existence. The overwriting is going to bring new files to the core of your WordPress version, files that are not corrupted and that won’t cause trouble. 

NOTE: After you do this replacement, we recommend to clear the browser cache. 

After all these steps, you can go to your browser and check whether the “Error establishing a database connection” message is still present. If it’s still there, cross over to the other sections of this article. Go step by step and see which solution might work for your particular database connection error issue. 

Repairing Corrupt Database

Sometimes databases get corrupted. WordPress is a busy site and as a user you or your collaborators must constantly install and uninstall a bunch of themes and plugins your site needs. If you happen to see this sentence while trying to login to the dashboard of your WordPress site, then it means there’s something going on with corrupt databases: “One or more database tables are unavailable. The database may need to be repaired.” The fronted piece of this puzzle you already know: “Error Establishing a Database Connection”. 

Luckily, WordPress contains a mode for database repair which you can use in situations like these. To do this, you have to add the following code to the bottom of your wp-config.php file:

define(‘WP_ALLOW_REPAIR’, true);

Afterward, you will need to go to this place on your WordPress site: https://_____.com/wp-admin/maint/repair.php. Here you can see two options: you can either repair and optimize the database or only repair it. The faster solution would be the second one, so if you’re in a hurry to fix your site (aren’t we all, always?!), make sure to choose that one. 

After you go through with the database repair, you have to make sure that you’ve taken out the code mentioned above that you placed in your wp-config.php file (if you don’t do this, everybody will be able to initiate the repair). 

If you’re using cPanel, the repair option can be run from the inside of the database screen of MySQL.

You could also initiate a repair from the insides of phpMyAdmin. If you want to do this, you’ll have to log in to phpMyAdmin, then click on your database, and make sure you select all the tables. After that find the “Repair table” option and click on it.  

A fourth option to run the repair is by using WP-CLI. You’ll have to put in this command: 

wp db repair

(For more documentation on usage, see the WordPress developer resources.)

Restore Your Site to the Latest Backup

Backups! Another reason why are they so important is that you can turn to them in troubled times such as this one. If nothing else works from the suggestions mentioned above, or you simply don’t have as much time to deal with it and you want a quicker solution, then this is the way to go. If you think that there won’t be much (or at all) data lost from the latest backup, then you can do it without any issues. If you’re on a good hosting provider, chances are they have their own backup tools/plugins and can help you restore both your files and your database. 

Database Server Issues 

Another last-minute solution (or cry for help) can be your hosting provider. If you don’t see any results with the other steps we’ve compiled here, then you can definitely turn to your host. The database connection error might also have to do with the database server of your host. A big number of hosts have constraints when it comes to their servers and the number of allowed connections to your site’s database at the same time. This means that too many simultaneous concurrent connections to your database can definitely cause an error such as this one. What can help in situations like these is a good caching plugin, one that can contribute to the minimization of your site’s interactions with the database.  

Now you see the reason why it’s so important to have a good quality hosting provider and why it pays off so much in the end. If you’re on a shared host, it means that the resources your site needs from the host’s servers are being used by others as well, which will affect your site one way or another. 

Conclusion

The “Error Establishing a Database Connection”, like any error, is an annoying one. Nobody wants to see their site go offline, and nobody wants to lose time tinkering in its backend. Sometimes, though, you gotta do what you gotta do. 

Here we tried to give you detailed descriptions of what to do when you set out to fix the database connection error in WordPress. We gave you the most common reasons why this might happen and what to do about it. We also reminded you about the importance of backup, both if everything else fails from the solutions above, but also even before setting out to tinker with anything in the database or files. 

We hope we helped you get your site back on track and we also hope that in the future you won’t have to experience any errors such as this one or the like! 

Leave A Response

* Denotes Required Field