Oh the dreaded “Error establishing a database connection,” dum, dum, dum (imagine ominous music playing). If you’re a seasoned WordPress designer or developer you can most likely jump right into fixing this error. But for those of you new to WordPress, this can be a scary error message.

You may see this error when trying to install WordPress manually or you’ll see this error in large black font on a white screen in your browser when you try to pull up your website or local development environment. The latter is the scariest version of this error because it usually catches you off guard.

Of course, any good managed WordPress host should configure everything for you and ensure that these errors never arise. But if you’re using a WordPress host that makes you install and manage WordPress yourself, or if you’re developing on your local computer, you may run into this issue.

Out of all the WordPress PHP files required to make WordPress run, wp-config.php is the most important because without that file, your site can’t connect to its database and your site won’t work. This file is where you define your database connection information such as Database Name, Username, Password, and Host. On hosts like Flywheel, you’re not actually able to edit this file, as it’s configured for you. You can safely skip this next reason if you’re using a managed host.

The most common reason for this error

The most common reason why you get the infamous “Error establishing a database connection” is due to incorrect database connection settings in wp-config.php. When moving a site from an old hosting company, you have to make sure to update the Database Name, Database Username, and Database Password in your wp-config.php file to reflect the new database on your new hosting.

Improperly moving your WordPress site

A common issue that I’ve seen is when someone moves their WordPress files to a new hosting company and then point the domain name to the new host, but they didn’t move their database.

Make your site blazing fast: Part 2

Last week, I talked about how to speed your site up with a focus on the front-end performance. And while that can be extremely helpful for speeding up your site, don’t forget – there’s the back-...

The site will still show up when you go to the URL and the site will still function. The issue here is that when you finally cancel your old hosting, the website will go down because you were connecting to the database on the old hosting account, thus producing the “Error establishing a database connection” error message.

The best practice is to move everything to your new hosting company and update your wp-config.php file to reflect the new database. That way you can confidently cancel your old hosting account without losing any data and seeing the dreaded “Error establishing a database connection” error.

If you’re on Flywheel, they’ll just move everything over for you and make sure that you’re up and running, taking the hassle out of having to figure out any of these configurations.

Your wp-config.php file is the first place you should start when trying to fix this issue. If you verify that your connection information is indeed correct, move on to these other fixes outlined below.

There can be a variety of reasons this error happens and I will take you through some additional scenarios. Don’t worry – you don’t need to be a developer wizard to fix this error.

Before you try any of these fixes below, make sure you create a backup of your database. You can do this via your hosting control panel by going to phpMyAdmin and then exporting the SQL file.

Let’s dive in shall we?

Cause 1. You forgot to update your wp-config.php file when you changed the database password

Updating a database password so your database is more secure is a really good thing to do. A strong password is the best kind of password. Remember that when you change the password for a database in your hosting control panel, you also need to change the password in your wp-config.php file.

The good news is that this is an easy fix. All you have to do is open your wp-config.php file and add the new password.

Download your wp-config.php file, open a text editor, and edit the following line:

define('DB_PASSWORD', 'password-goes-here');

Add your new password, save the wp-config.php file, and upload via FTP. Refresh your site and see if your site comes back. If so, you’re done. Congrats – you win all the Internet points!

Note: Make sure to leave the single quotes around the password, and there should be no spaces between the single quotes and your password either.

Easy peasy right?

Essentially, what you are doing is making sure that your database connection information is updated to reflect the new database password.

Once again, if you’re on a host like Flywheel, this step isn’t applicable to you and you can safely move on!

Cause 2. You entered your database information incorrectly during the famous WordPress “5 minute install”

Typos are literally the bane of our existence when working online; one little typo can crash a website and in this case, the wrong underscore or forgetting a letter or number from the database name, username, or password has the same crashing effect.

Most WordPress installs are handled via your hosting control panel using a wizard these days, or done completely for you on Managed WordPress. But some folks do like to install manually. I hear manual installs are still a thing.

If you chose to install WordPress the Ye Olde Fashioned way by manually creating a database and manually uploading the WordPress software via FTP, you need to make sure to save the database user information when you created your database. This is where copy and paste really comes in handy.

However, make sure that when copying this information, you only copy the text that you need. Did you know that copying an extra blank space after the database name, username or password will be read as a character? This extra blank character will give you errors when the installer tries to connect to your database.

Also, make sure that you are entering the information in the proper field during install. I actually had a brain fart once and realized that I was entering the database name in the wrong field. Once fixed, the install went off without a hitch!

Cause 3. When moving a WordPress website to a new host, DB_HOST may be something unique to that host

Even though you updated your wp-config.php file to reflect the new database connection information at your new hosting company, you may have to change your DB_HOST Field.

This problem is more rare, but it does happen. Some hosting companies use their own unique values when defining the DB_Host parameter in wp-config, but this is not always the case. Other hosts actually define a URL to the MySQL database server and that needs to be reflected as the value for DB_HOST. Some users have also had success using their hosting I.P address in place of a MySQL URL or localhost, so you can try that too.

If you’re on Flywheel, this is automatically handled for you, so you don’t have to worry at all.

Cause 4. Your database gets corrupted

This error is not the same as “Error establishing a database connection” but it is slightly related. Sometimes the front end of your website works fine, but you get an error such as “One or more database tables are unavailable, the database may need to be repaired” on the backend. This means that you should repair the database.

Here’s the fix for this error:

Open your wp-config.php file and go to the section that defines your database name, username, password and host. Under Host define the following:

define('WP_ALLOW_REPAIR', true);

Then save your wp-config.php file, upload via FTP, and then go to this URL:

This will pull up a page with two options. Option one is a button that says “Repair Database” and the second option is a button that says “Repair and Optimize Database”

I have to reiterate the importance of backing up your database before doing this step. Even though you can’t connect doesn’t mean that you shouldn’t have a backup.

Click the “Repair Database” option and once the repair process is finished open a new tab and go to your URL and see if the “Error establishing a database connection” message is gone and if your site is back to normal.

If this fix doesn’t work, and the above fixes don’t work there is one last cause you should know about.

Most managed hosts will backup your data daily for you, so if this not-so-great scenario happens, it’s sometimes just easier to restore from yesterday’s backup and keep on moving.

Cause 5. The MySQL database server is down.

This tends to happen for folks that are pushing their shared hosting to its limit. If your website gets a lot of traffic, this can simply overwhelm the database server. High fives to you for having a website that gets all that sweet, sweet traffic, but if you get the “Error establishing a database connection” message and you have tried the other fixes, you may need to upgrade.

On a shared host, tons of websites can be crammed onto the same server. If one gets a lot of traffic or is just being a noisy neighbor in general, it can cause a huge problem for the rest of the sites. On managed hosts like Flywheel, each site gets its own server, so this problem is easily handled.

But before jumping right into a hosting upgrade you should call your hosting company and ask them to check the status of the database server. Perhaps there is a technical issue, or maybe your hosting company sent you an email about scheduled server maintenance and you missed that email. While highly improbable that you would see the “Error establishing a database connection” message resulting from server maintenance, I have seen that once in my career and either way, It’s worth a phone call to find out.

Talk to your hosting company and explain that you’ve tried these various fixes to no avail and ask them to look into it. If they tell you that your site is producing quite a load on the server and recommend a hosting upgrade, congratulations you’re awesome! Remember these upgrades mean that your site is kicking butt!

The wrap up

As you can see fixing the “Error Establishing The Database Connection” error is not as scary as you thought. It just takes a little due diligence to check that you are defining the proper database settings in your wp-config.php file. In some cases it takes some deeper digging to resolve the issue. And at the end of the day, your hosting company is there to have your back.

Learn more about Flywheel

Whatever your work environment, Flywheel’s powerful WordPress platform removes all the hassles of hosting, streamlines your processes, and lets you get back to doing your best work.

Learn more here.