How to Fix the Error Establishing a Database Connection in WordPress

By , Updated: September 18, 2017

error establishing a database connection

The “error establishing a database connection” is probably one of the most common and frightening errors that WordPress users can encounter. It’s definitely a close tie with the white screen of death (WSOD).  This error means your website is no longer communicating or has access to your database, and thus your entire website goes down. This is not something to be taken lightly and you should try and resolve this immediately as this can directly affect your sales, traffic, and analytics. But don’t worry, today we’ll discuss some common scenarios that cause this error and some easy ways to get your site back up and running in no time.

What is the Error Establishing a Database Connection?

All of the information on your WordPress site, such as post data, page data, meta information, plugin settings, login information, etc. is stored in your MySQL database. The only data that isn’t stored there is media content such as images and your theme/plugin/core files such as index.php, wp-login.php, etc. When someone visits your website, PHP executes the code on the page and queries the information from the database, which then displays it to the visitor in their browser.

If for some reason this isn’t working properly, you are left with the error establishing a database connection message, as seen below. The entire page is blank because no data can be retrieved to render the page, as the connection is not working properly. Not only does this break the frontend of your site, but it will also prevent you from accessing your WordPress dashboard.

Example of error establishing a database connection
Example of error establishing a database connection

When visitors try to access your site while this is happening it will generate a 500 HTTP status code in your logs. This same status code appears when there is an “internal server error”. It essentially means that something went wrong on the server and the requested resource was not delivered. When everything is working properly your site will generate a 200 HTTP status code, which means everything is fine.

Error establishing a database connection 500 error
Error establishing a database connection 500 error

Common Scenarios That Cause This Error

So why exactly does this happen? Well, here are a few common reasons below. And don’t worry, we will go into each of these more in-depth so you can know how to fix them. Typically you can resolve this error in under 15 minutes.

  • The most common issue is that your database login credentials are incorrect. Your WordPress site uses separate login information to connect to its MySQL database.
  • Your database is corrupted. With so many moving parts with themes, plugins, and users constantly deleting and installing them, sometimes databases get corrupted. This can be due to a missing or individually corrupted table, or perhaps some information was deleted by accident.
  • You may have corrupt files in your WordPress installation. This can even happen sometimes due to hackers.
  • Issues with your database server. A number of things could be wrong on the web hosts end, such as the database being overloaded from a traffic spike or unresponsive from too many concurrent connections. This is actually quite common with shared hosts as they are utilizing the same resources for a lot of users on the same servers.

How to Fix the Error Establishing a Database Connection

Before you start troubleshooting the error, we always recommend taking a backup. A lot of the recommendations below involve manipulating information in your database, so you don’t want to make things worse. You should always backup before trying to fix things on your WordPress site no matter how tech savvy you think you are. You can use a popular WordPress backup plugin such as UpdraftPlus or Duplicator to backup both your files and your database.

You can never have too many backups; no matter how tech savvy you think you are. 😉 Click to Tweet

If you are a Kinsta user, you can simply take advantage of our one-click backup feature. Simply click into your WordPress site in MyKinsta, click on “Backups” and then on “Backup Now.”

Backup WordPress site
Backup WordPress site

You then also have the option to restore a backup to production or staging. Or you can manually backup your MySQL database using phpMyAdmin. Once you have a successful backup, it is then time to start troubleshooting your database connection issues.

1. Check Your Database Login Credentials

The very first thing to do is check to ensure your database login credentials are correct. This is by far the most common reason why the error establishing a database connection message occurs. Especially right after people migrate to a new hosting provider. The connection details for your WordPress site are stored in the wp-config.php file which is generally located at the root of your WordPress site. It contains four important pieces of information that all need to be correct in order for the connection to successfully take place.

    • 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');

To access your wp-config.php file you can connect to your site via SFTP and browse to the root of your site. Or if you are using cPanel, you can click on “File Manager,” browse to the root of your site, and right click to edit the file.

cPanel file manager
cPanel file manager

Here is an example below of what the file looks like when opened.

wp-config.php credentials
wp-config.php credentials

You need to now check your current values against those on your server to ensure they are correct. Follow the directions below for cPanel and Kinsta users.

Check Database Credentials in cPanel

The first thing to check is the database name. To do this you will need to login to phpMyAdmin in cPanel under the Databases section.

cpanel phpmyadmin
cPanel phpMyAdmin

On the left-hand side, you should see your database name at the bottom. You can ignore the “information_schema” database as this is something used by the host. You will then want to compare that name against the DB_NAME value in your wp-config.php file. If they match, then this isn’t the problem. If they don’t match, then you need to update your wp-config.php file.

cPanel database name
cPanel database name

You can also verify that this is the correct database by ensuring that it contains your WordPress site’s URL. To do this, simply click on the database, then click into the wp_options table (this might be named something slightly different for security purposes, such as wpxx_options). At the top of the table, you will see values for your site’s URL and name. If these match your current site you can rest assured you are in the right place.

Check site URL in phpMyAdmin
Check site URL in phpMyAdmin

If your database name was already correct and you are still getting the error establishing a database connection message then you will also want to check your username and password. To do this you will need to create a new PHP file in the root directory of your WordPress site, and input the following code. You can name it whatever you want, such as checkdb.php. Simply change the values of db_user and db_password with those that are in your wp-config.php file.

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

Then browse to the file on your WordPress site: https://yourdomain.com/checkdb.php. If you get a “MySQL Error: Access denied” then you know your username or password is wrong and you will need to continue to the next step to reset your credentials.

Access denied mySQL
Access denied MySQL

Below is the message you want to see, “Database connection is working properly.” But of course, if it was then you wouldn’t be here. Be sure to delete/remove this file after you are done testing.

Database connection working properly
Database connection working properly

So next you need to reset your username and password. In cPanel, click on MySQL Databases under the Databases section.

cPanel MySQL databases
cPanel MySQL databases

Scroll down and create a new MySQL user. Try and pick a unique username and password so that they can’t easily be guessed. The password generator tool they provide actually works great. Then click on “Create User.” You could alternatively also change the password on this screen for the current database user that already exists.

Create new MySQL user
Create new MySQL user

Then scroll down and add your new user to your database. The next screen will ask which privileges you want to assign, select “All Privileges.”

Add user to database in cPanel
Add user to database in cPanel

Then take those new credentials and update your wp-config.php file. You will want to update the DB_USER and DB_PASSWORD values. You could also run the test file again from earlier. This should then resolve your credentials issue. If not, it could be that you still have the wrong hostname (DB_HOST). Some hosts use different values, see a list of some common DB host values. Typically this will simply be localhost. But you can always reach out to your hosting provider or check their documentation if you aren’t sure. Some might also use 127.0.0.1 instead of localhost.

If you have followed everything above and are still receiving the error establishing a database connection message, the proceed to the next troubleshooting steps below.

Check Database Credentials With Kinsta

If you are a Kinsta user, the process of checking your credentials against your wp-config.php file and the server are much easier! All you need to do is click on the info section of your site, and at towards the bottom, you will see the database name, database username, and database password. By default, Kinsta uses localhost for the DB_HOST.

Kinsta database login credentials
Kinsta database login credentials

Then take those new credentials and update your wp-config.php file. You will want to update the DB_USER and DB_PASSWORD values. This should then resolve your credentials issue. If you need to reset these credentials, simply reach out to our support team. If you have followed everything above and are still receiving the error establishing a database connection message, the proceed to the next troubleshooting steps below.

2. Repairing Corrupt Database

In some cases, it could be that your database has become corrupt. This can occasionally happen (although not very often) as over time hundreds of tables are constantly added/removed by new plugins and themes. If you try to login to your WordPress site’s dashboard and are receiving the following error, it means your database is corrupt: “One or more database tables are unavailable. The database may need to be repaired.” It is important to note that you might only see this error on the back-end, whereas you see the error establishing a database connection message on the frontend.

WordPress actually has a database repair mode which you can initiate. Simply add the following to the bottom of your wp-config.php file.

define('WP_ALLOW_REPAIR', true);
WordPress repair mode
WordPress repair mode

Then browse to the following location on your WordPress site: https://yourdomain.com/wp-admin/maint/repair.php. You will then have the option to repair the database or repair and optimize the database. Since you are probably troubleshooting an outage on your site at the moment, we recommend going with the repair database option as it is quicker.

WordPress repair database
WordPress repair database

After running the repair of the database above, ensure that you remove the line of code you added to your wp-config.php file, otherwise anyone could run the repair. If you are running cPanel you can also run a repair from within the MySQL databases screen.

cPanel repair database
cPanel repair database

Or you could run a repair from within phpMyAdmin. Simply log in to phpMyAdmin, click on your database, and select all the tables. Then from the dropdown click on “Repair table.” This is essentially just running the REPAIR TABLE command.

Repair tables in phpMyAdmin
Repair tables in phpMyAdmin

If you are wanting to optimize your database, we have some great tutorials on how to optimize WordPress revisions for performance, along with how to convert your MyISAM tables to InnoDB. If you are still having issues on your site, then proceed to the next troubleshooting step.

3. Fixing Corrupt Files

The next possible reason you might be seeing the error establishing a database connection message is that your files have become corrupt. Whether this originated from an issue with transferring files via FTP, a hacker gaining access to your site or a problem with your host, you can quickly fix this. However, again we recommend taking a backup of your site before trying this.

You are basically going to replace the core version of WordPress on your site. You aren’t touching your plugins, themes, or media, just the WordPress installation itself. To do this, you will need to download a fresh copy of WordPress from WordPress.org.

Download WordPress
Download WordPress

Unzip this file on your computer. Inside, you will want to delete the wp-content folder, as well as the wp-config-sample.php file.

Delete wp-content folder
Delete wp-content folder

Then upload the remaining files via SFTP to your site, overwriting your existing files. This will replace all the problematic files and ensure you have fresh ones that are clean and not corrupted. It is recommended to clear your browser cache after doing this. Then check your WordPress site to see if the error still exists.

4. Issues With Your Database Server

If nothing above has helped resolve your issue, then we highly recommend checking with your hosting provider as it could be an issue with your database server. For example, if there are too many concurrent connections to your database at once, it could generate the error. This is because a lot of hosts have limits on their servers on how many connections are allowed at once. Utilizing a caching plugin can help minimize the database interactions on your site. If you are a Kinsta client, you don’t need caching plugins, as we have fast server-level caching in place.

This problem can happen a lot on shared hosts as someone else could theoretically be affecting your site. This is because shared hosts utilize all the same resources on servers. This is yet another reason why we always recommend going with a high-performance managed WordPress host, so things aren’t overcrowded. It also means the environment is typically fine-tuned to handle large amounts of traffic specifically to WordPress sites.

The knowledgeable Kinsta support team is always a click away on the bottom right side of the dashboard and available 24×7 if you need help. And don’t forget we have representatives in to assist you in both English and Spanish.

Contact Kinsta support
Contact Kinsta support

5. Restore Latest Backup

And last but not least, you can always resort to a backup if needed. In some cases, this might be a faster way to resolve the issue if you aren’t worried about losing any data between when your last backup was taken. Many hosts have their own backup restore process. Remember that you might need to restore both your database and your files.

If you are Kinsta user you can easily restore a backup of your site within the Backups section of your site. Simply choose the time you want to revert to and click on “Restore.”

Restore WordPress backup
Restore WordPress backup

You will then be prompted to confirm the restore. Simply enter your site name and click on “OK.” It also creates a backup at the time of restore so you can undo the restoration if needed.

Confirm WordPress restore
Confirm WordPress restore

Summary

As you can see there are quite a few ways fix the error establishing a database connection in WordPress. The most common being invalid credentials in the wp-config.php file. Checking to ensure those are correct is the best place to start. The last thing you want for a website is to experience downtime. So hopefully one of the steps above helped you get your site back up and running.

Have you experienced the error establishing a database connection message on your site? If so, were you able to resolve it? Let us know below in the comments.