How to Fix the Error Establishing a Database Connection in WordPress

How to Fix the Error Establishing a Database Connection in WordPress

One of the single most frustrating, most frightening and discouraging things when building a website, is when things go wrong… Oftentimes, certain errors or mishaps can be fixed relatively quickly and painlessly, while other times, you may have to do a little bit more work to troubleshoot.

One such instance is when the Error Establishing a Database Connection alert presents itself. The alert indicates that your website is down and is not displaying at all. Every second that you see this message is another second that you’re losing web traffic, unsettling your rankings and reputation and leaving a sour taste in the mouths of potential customers who are forced to look for an alternate website.

The Error Establishing a Database Connection alert is particularly frustrating as there are a plethora of possible reasons as to why the alert is showing. There’s no real quick fix here, the only way to solve this problem and restore your website is by doing bit more detective work.

In the following post, we discuss a few methods that’ll help you try to figure out why this alert is displaying.

What is the Error Establishing a Database Connection alert?

Before jumping into the explanations of how to go about solving the problem, it is worth understanding why this error message is displaying in the first place.

WordPress websites are made up of two essential components: site files and a database. The site files are the actual files that are stored on your server, while the database (a SQL database, managed through a platform called phpMyAdmin) enables these files to work together in the correct way.

In application, if you were to enter the URL of a web page into the browser bar and hit enter, the server begins working through the MySQL database and displays the sought after PHP file associated with the website’s homepage. In the case of the home page, this is typically the index.php file. Once the process is initiated, all of the content associated with the specific page (images, text, videos etc.) will display. Even though the WordPress system stores content in the wp-content folder and not per page, the correct files will display as they’re retrieved and displayed via PHP.

Essentially, the “Error Establishing a Database Connection” alert is letting you know that for some or other reason, the website’s SQL database is unable to connect with the files on the website’s server.

While there are a number of reasons as to why this error message may be displaying, there are common main causes are often (we’ll go into more detail on each of these later):

  1. The server is down
  2. The database is corrupt
  3. The login details are incorrect

How to Fix the Error Establishing a Database Connection in WordPress

Now, we’ll cover a few common workarounds to help you figure out where the problem is coming from.

The problem-solving methods below can become tricky and intricate, so proceed with caution and care.

Contact Your Hosting Service Provider

The Error Establishing a Database Connection could be due to a malfunction of the server. There are countless reasons as to why a server would go down including a massive spike in site traffic, overuse of resources, hacking or just generally old or faulty hardware.

To make sure whether the problem is yours or not, we recommend contacting your host and finding out whether something has happened to the server that your site is hosted on. If you have great hosting that comes with amazing support, this shouldn’t be a problem.

If the server is, in fact, playing up, your host will advise you on what you can do in the interim while they make amends. If your server is 100% fine, you’ll need to investigate your website’s database.

Repair the Corrupt Database

Even the simplest WordPress website has an intricate database structure, and, with so many moving parts, any number of mishaps can cause a database to become corrupt.

You could have installed an unsavory plugin, your data transfer could have been interrupted, or, if you’ve been looking around the phpMyAdmin console or tinkering with the database, you could have simply deleted portions of the database by accident. Each of the scenarios would lead to a corrupt database which would display the error alert, “One or more database tables are unavailable. The database may need to be repaired.”

Note, a corrupt database will only display the above-mentioned error alert in the back end, not the front end. If you are trying to log in via the wp-admin page and you receive the “One or more database tables are unavailable.” message, you’ll need to repair the database.

Thankfully, this process is relatively simple. To put the WordPress website in repair mode, add the following line of code to your wp-config.php file.

define('WP_ALLOW_REPAIR', true);

WordPress Repair Mode

To find the wp-config.php file, you’ll need to access your website’s site files on the server. To do so, open cPanel, click on the Files menu and click on the File Manager icon. The FIle Manager console will open in a new tab. Search for the public_html folder and browse through the file list until you locate wp-config.php. You can either edit the file right from within the File Manager console (simply right click on the file and select Edit), or FTP the file down and up again using an FTP client such as FileZilla or Cyberduck.

Once the file has been saved, copy and paste the following URL into your browser bar: https://websitename.com/wp-admin/maint/repair.php (replace ‘websitename’ with the name of your website).

WordPress Repair Database


Now you’ll be met with two options – Repair Database and Repair and Optimize Database. Either option will suffice, except Repair and Optimize Database will take a bit longer. If you don’t have time on your side, select Repair Database.

Note: In Repair more, your WordPress website is not secure. It is crucial that you remember to remove the define(‘WP_ALLOW_REPAIR’, true); line from the wp-config.php file. As soon as the repair is complete, return to the wp-config.php file immediately, remove the line and save the file.

If the Error Establishing a Database Connection alert is gone, and your website is displaying correctly, great! If you’re still getting the error alert, you need to do some more investigating into your website’s database. The process of which goes as follows:

  1. Check the wp-config.php file to make sure that the database login details are correct, if the login details are correct but you still get an error message, then,
  2. Check that the website is connected to the correct database, if the correct database is linked but you still get an error message,
  3. Check that the correct username and password are associated to the website, if they are and there is still the error message,
  4. Change the username and password of the database.

Check the Login Details in the wp-config File

At this point of troubleshooting the error alert message, you need to double check that the correct database is linked to the website and that the login details for the database are entered correctly without any odd typos, weird spaces etc..

phpMyAdmin uses a different set of login details to that associated with the WordPress website itself.

If the incorrect login details have been used to access the database, most likely because they have been changed and not updated, there’ll be an error in connecting to the database. Scenarios such as changing your hosting service provider or alerting any information about your database without updating the wp-config file could cause it’s login details to be rendered as incorrect.

To check the login details in the wp-config file you’ll need to enter the website’s server. To do so, log in to cPanel and under the Files tab, select File Manager.

cPanel

The File Manager will open in a new tab. Once opened, you’ll see all of the files associated with your server. In the left-hand tab, locate and click on a folder named public_html. Look in the right-hand tab and search for a file named wp-config.php.

cPanel File Manager

Right click on thewp-config.php file.

cPanel File Manager wp-config File

Now, you’ll see a menu appear. You can either click View to assess the login details or Edit to change the details on the live server. We don’t recommend this, instead, we suggest that you download the wp-config file and edit the copy that will be saved on your computer. For this, use a text editor such as Sublime or Brackets.

Once you open the wp-config.php file, you’ll see all of the login credentials relating to your database.

wp-config File

These login credentials include:

  1. The database name (“DB_NAME”);
  2. The database login username (“DB_USER”)
  3. The database login password (“DB_PASSWORD”)
  4. The database host (“DB_HOST”)

Note: This wp-config file is a screenshot from a local site – AGSandDStestsite – that I often use to play around with products, test random work related things and use in the event that I have to include demonstration imagery. Even though this isn’t a real live site, the database name, username, password and host details would all be found in the exact same place, and would present in the same format.

If any of these variables are incorrect, then you’ve found the reason for your error alert. If for some reason you don’t know the database details, you’ll need to do some more hard graft. These processes are a little bit tricky, they entail checking your database details in the phpMyAdmin console. To avoid additional unwanted mishaps, proceed with caution.

Check Your WordPress Website’s Database Credentials in phpMyAdmin

To make sure that your database credentials are correct, you’ll need to make sure that:

  1. You have the correct database associated with your website,
  2. That you have the correct username and password in your wp-config.php file

First things first, make sure that you have the correct database. To do this you need to access the phpMyAdmin console. Log into your cPanel and navigate to the tab titled Databases. Here, click on the icon titled phpMyAdmin.

cPanel phpMyAdmin

The phpMyAdmin console will open up in another tab. Here you’ll find the database relating to your website, or a list of multiple databases if you run multiple websites on your server.

Note: To not risk poking around on a live website, I’m returning to the local development environment for screenshots of the next few steps. Between my localhost phpMyAdmin console and that of a live website, there may be a few differences in appearance, but essentially, the nuts and bolts are identical.

phpMyAdmin

Once you open up phpMyAdmin, you’ll all of the databases hosted on the server in the left-hand column, specifically the database of the website in question. The database will have the exact same name as that of the DB_NAME value found earlier in the wp-config.php file.

If you’d like to be extra sure that the database is correct, click on the name of the database and a list of ‘tables’ will appear in the right-hand column.

phpMyAdmin Database

In the right-hand side column, scroll through the tables until you find wp-options and click on it. This may be named something different, so just keep an eye out for ‘options’.

phpMyAdmin wp-options

At this point, the wp-options table will open, and at the very top of the wp-options table, you’ll see values for the website’s URLs (in site_url and home). If these values match the URL of your website in question, you can relax.

phpMyAdmin-Correct-Database

If these database names match and the URL is correct, you can rest assured knowing that database is not the problem, that the correct database is in fact hooked to your website and there is more troubleshooting to be done.

If you’re still receiving the error message, you need to go a step further and assess your username and password. Again, this is another complicated process, so be cautious.

Checking the Username and Password of the Database

To check that the username and password are correct, you’ll need to create a new file using your text editor and add it to your server. Open up your text editor of choice (Brackets or Sublime) and paste in the following code:


 $test = mysql_connect('localhost', 'db_user', 'db_password');
 if (!$test) {
 die('MySQL Error: ' . mysql_error());
 }
 echo 'Database connection is working';
 mysql_close($testConnection);

You can name this file anything really. Here, I’ve called it checkdb.php. Now, change the values of db_user and db_password with those that were found in your wp-config.php file and save. Next, to add the file to the root folder of your WordPress directory, you can use an FTP client such as FileZilla or Cyberduck.

Once the file is loaded to your server, enter the URL of your website followed by a forward slash and the name of the file you’ve just added (including the .php extension at the end). For example: https://websitename.com/checkdb.php (replace ‘websitename’ with the name of your website).

Now, if you see a response that says “Database connection is working properly!” you know that the username and password are correct. With the correct username and password, and the correct database, you can rule out for certain that there is no issue with your database whatsoever.

If you receiving an alert message that says “MySQL Error: Access denied”, it means that your username and password are incorrect. At this point, you need to change your username and password.

Changing the Username and Password of the Database

To reset your username and password, return to your website’s cPanel, open the Databases tab and click on the MySQL Databases icon.

cPanel-MySQL-Databases

Once you’re inside the MySQL Databases console, scroll all the way down until you see a section titled MySQL Users and “Add New User”. Here, enter a new username and assign a unique password (the password generator works really well). Make sure you save these login credentials somewhere safe. Click Create User and you’ll be met with a notification that says the new user was created successfully.

MySQL-Databases-Add-New-User

The next step is to add the new user to the database. From the User menu, select the name of the new user profile you’ve just created. From the Database menu, select the name of the database relating to the website in question. Click Add. You’ll be taking to another screen that’ll ask you which permissions you’d like the new user to have. Here elect the ‘All Privileges’ checkbox.

MySQL-Databases-Add-User-to-Database

At this point, you need to revisit your wp-config file (navigate to cPanel > File Manager search for the public_html folder and locate the wp-config file therein) and enter in the new username (DB_USER) and password (DB_PASSWORD) associated with your database.

If the error message still persists, there may be an issue with the DB_HOST hostname. This value can change depending on who you host your website with. Click here to view a list of common DB_host values. At this point, it’s worth calling your hosting service provider to query the DB_HOST value.

We want to hear from you!

Have you ever experienced the dreaded “Error Establishing a Database Connection” alert? How did you solve it? Please feel free to share any comments or questions below. We love receiving your feedback!

Thanks for reading!

Lisa-Robyn Keown

Lisa-Robyn is a qualified copywriter and brand strategist from Cape Town, South Africa.