How to fix the ‘Error Establishing a Database Connection’ in WordPress

Nothing creates a sinking feeling like being greeted with an error screen and the message “Error establishing a database connection”, after all a non-functioning website means traffic that may never come back – lost subscribers, lost customers, lost opportunity – and lost revenue.

WordPress is a free and extremely popular site management platform, but this is a fairly well known WordPress problem.

What causes this error to occur, and what does it mean? More to the point, how can you just correct the problem and get your site working again?

Let’s take a look at the problem and what could have caused it, and we’ll go through steps for troubleshooting and fixing the error.

error-establishing-database-connection-wordpress

What’s the Problem with My Database?

If you understand how WordPress functions to display your web pages, you’ll have a better idea where the problem comes from and why it can be so crippling.

WordPress is built using PHP and MySQL. The information that makes up your website is stored in a MySQL database, and PHP scripts tell WordPress how to store and retrieve that information to create and update your pages.

Every time a page or post is added, information about it is written to your MySQL database. Every widget setting and active plugin gets noted in MySQL. When the page is loaded, it’s built on the fly. There’s a separate PHP statement to retrieve every element, from frames, colors, and titles to dates and fonts.

When you get the message “Error establishing a database connection” WordPress is telling your that your PHP code is unable to connect with your site’s MySQL database to retrieve the information it needs to put a page together.

That’s why the error is all you get, rather than an incorrectly-displayed page. Without the database, there isn’t any information available to construct a page. One could rely on HTML pages for certain needs, but that still leaves the problem and defeats the whole purpose of having WordPress and the advantages of PHP.

 

What Causes the Database Connection Error?

While the error is pretty straight-forward, the error page unfortunately tells you nothing about the problems which cause it – something hopefully some WordPress guru will address in the future. The fact is, there could be a number of reasons why your database is inaccessible. Unless you’ve really been tinkering with your PHP and site settings, the common causes fall into one or more of these three basic categories:

1. Login Credentials

Your database requires two separate items authenticate any user, WordPress or otherwise. That’s your login name and password. If those credentials have been changed, your database can’t be accessed, and no info means no page.

2. Corrupt Database

It does happen, for several different reasons, from malware or bad plugins, to problems at your host server (hopefully a reputable host company will have things running again ASAP).

3. Corrupt Files

Sometimes a single php file can have internal errors, if for instance you’ve had some kind of malware or a bad plugin that doesn’t work quite like it’s supposed to. Sometimes it’s not the php but another file the php is asked to open as part of your page.

4. Server not Available

Sometimes the server just can’t be reached. It may be down for maintenance, overwhelmed with traffic and unable to support new connections. Maybe there is a problem with your ISP and Internet connection, or browser.

Some of these things may be beyond your control, so how can you identify the issue and fix it?

Troubleshooting Your Database Connection Problem

1. Login Credentials

If you’re still having problems it may be a MySQL credentials issue. How could that happen? Things like changing hosting companies, resetting passwords, changing database names, or running the wrong MySQL queries could cause such problems if your wp-config file didn’t get updated to reflect the new information.

Go back to your wp-config file if you didn’t keep it open, and look for a section somewhere near the start of the file that looks like this:

 define('DB_NAME', 'database-name');
 define('DB_USER', 'database-username');
 define('DB_PASSWORD', 'database-password');
 define('DB_HOST', 'localhost');

You can see the information WordPress needs to connect to your database: database name, username, password, and host computer. If any one of these is wrong, WordPress can’t connect to the data it needs. If in doubt, you can check on your database from your cPanel dashboard, which usually has a feature called PHPMyAdmin for using databases outside of WordPress. You might want to make a backup of the database first. Since you’ll be directly changing your site’s data from PHPMyAdmin, a mistake at this point could cause even more damage.

Log into PHPMyAdmin, and you’ll see a list of databases on the left. Click the one that matches the name of the database you have in your wp-config.php file (the text value to right of DB_NAME). If you don’t see any database listed, the problem might be with the host server, not the database, because there absolutely should be a MySQL database.
When you click on your database name, you’ll a screen listing the names of the tables in the database. If in doubt, click “Browse” next to the table named wp-options, and you should find your site name and URL along with other settings. If it’s there, and the name matches your wp-config.php entry, you have the right database.

If the URL is right, but your wp-config file is wrong, change the name there to match the right database.

Next, verify the username and password. There are two ways to do this, but the second is much easier.

1. Create a brief .php file to test whether you can connect to the database with the credentials from wp-config. Into a new text file type:

<?php
 $link = mysql_connect('localhost', 'root', 'password');
 if (!$link) {
 die('Could not connect: ' . mysql_error());
 }
 echo 'Connected successfully';
 mysql_close($link);
 ?>

Save the file to your WordPress directory as “connectiontest.php” or whatever you like (as long as you have the “.php” suffix). Type the URL of the file into your browser and try it; you’ll see either the “Connected successfully” message or the “Could not connect” message.

If the username and password isn’t working, just go to step 2.

2. If you can’t find the given username and password in the table, go ahead and create a new username and password in the wp-options table – just make sure you also make the changes to the wp-config file.

The best way to do this is from another cPanel tool called “MySQL Databases”. Click on that and scroll to “MySQL Users: Add New User”. Create you new username and password, and make sure the changes are updated in wp-config. Click “Create User” and then find “Add User to Database”. Select the username and password you just created, and click “Add”. If you’ve made the exact same entries in your wp-config, your MySQL credentials are now correct.

If the database connection error persists, the problem might be the DB_HOST entry in wp-config. Most of the time this will be the usual “localhost”, but your hosting company may use different settings. Consult any tutorials offered by your hosting company, or contact them and ask. If still in doubt, or impatient, you can visit the WordPress Codex to see some common options you could try.

Another possible problem in the wp-options table might be the way your URL appears. If the entry for that somehow got changed, you can correct it with a simple MySQL statement from PHPMyAdmin:

UPDATE wp_options SET option_value='YOUR_SITE_URL' WHERE option_name='siteurl'

2. Corrupt Database

There may be a database issue if wp-admin works fine, but the public site won’t load. You also may be looking at database corruption if you only get the error when trying to access your wp-admin, or if you’re getting other errors at login such as: “One or more database tables are unavailable. The database may need to be repaired.”

It’s not something you would know unless you’ve read WordPress tutorials or spent time on forums, but WordPress provides an easy way to recover your database. Before you can try it, the feature has to be enabled in your wp-config.php file where you find installation settings. Go to your host account cPanel, File Manager, and open the WordPress root directory file.

Open the wp-config file for editing, and add this line of code:

define('WP_ALLOW_REPAIR', true);

Now you can optimize and repair the MySQL database. Navigate to:
www.yourwebsite.com/wp-admin/maint/repair.php where “yourwebsite.com” is of course your actual URL.

On this new page you’ll see two buttons labeled: “Repair Database” and “Repair and Optimize Database”. Choose either to get the job done; but if you choose the “optimize” button it will take longer, and getting your site up is paramount.

Optimizing your database at this point probably isn’t the problem, anyway. While optimizing normally couldn’t hurt, there’s always the chance that it could lead to other problems you don’t want to address right now. There are other ways to optimize and clean your database. Several WordPress plugins have been made available, as well as through PHPMyAdmin.

(Note: this repair page is not enabled by default because it is unsecured (otherwise you wouldn’t be able to reach it). Anyone who knows WordPress could access your site and potentially mess with your MySQL, so be sure to remove that line of code from your wp-config file when you’re done.)

You can leave wp-config open in the meantime until the error is resolved and your website is up and running. If you’re still having problems, you’ll need wp-config again.

 

3. Corrupt Files

If you determine that your database is OK and sync’d up with your credentials, a bad file might be the cause. Users report that sometimes re-uploading the basic WordPress files fixes the connection issues. Exactly why would be hard to determine without going through all those files, a tall order for anybody, even someone proficient with php. Sometimes it just has to do with file permissions, settings, or variables in crucial files such as wp-content which has settings for important page features like themes, media, and plugins.

To reset WordPress files in one step, you’ll need to download the latest version from WordPress.org. Unzip the files on your computer and delete wp-config.php and wp-content.php. These will reflect all the changes that have been made to your site, and over-writing the exiting files could undo all of it. After these are deleted, go to your host cPanel and upload the remaining files to your WordPress root folder.

You might want to use an FTP tool, as doing them manually is error-prone and could take quite a while.

If nobody’s made harmful changes to wp-config or wp-content, you should be able to safely overwrite and replace existing WordPress files on your site with the pristine versions. Hopefully this will correct any file issues. At least from a WordPress standpoint. If you uploaded anything just prior to the connection errors, especially some third-party script for your widgets, remove it and try again.

Others have reported more elusive problems not fixed by any of the above. You might have a bad plugin; to check on this you could go in and disable all of them, then re-activate one-by-one and see if connectivity is restored.

The simplest way to do this is through the wp-admin dashboard, but if you can’t reach it, go to PHPMyAdmin in your host cPanel.

 

sqlbox

Open your database, and on the SQL tab type in:

SELECT *FROM wp_options WHERE option_name = 'active_plugins';

and click “Go”.

Click on “Edit” to see the query output, which should be something like:

a:4:
 {
 i:0; s:23: ”NameOfFirstPlugin/PluginOne.php”;
 i:1; s:25: ”NameOfSecondPlugin/PluginTwo.php”;
 i:2; s:43; ”NameOfThirdPlugin/PluginThree.php”;
 i:3; s:27: ”NameOfFourthPlugin/PluginFour.php”;
 }

Note: Always back up your database before making changes. Speaking as someone who’s made the mistake of not doing it, that can’t be stressed enough. Your site won’t run without it.

When you’re up and running, try one of these plugins to make your WordPress backups easier.

Copy and paste the entire entry to Notepad or some other text editor for reference. Delete all the entries. You can do this quickly by changing the a:4:{} entry to a:0:{}. When relisting them, be sure to add them back in the same way they are listed in your Notepad file.

If you can identify the offending plugin, simply leave out the entry, renumber the other entries and the a: count, and find a better plugin!

Some users have reported problems with transients, which reflect calls made for information that are cached in wp-options. WordPress is supposed to automatically delete these entries and recreate them as needed. Sometimes it doesn’t; in fact, you may end up with hundreds of useless entries. Normally, this isn’t a problem, but the entries do include php variables, and complications can occur. They are easy to remove: just go to PHPMyAdmin and run:

DELETE FROM `wp_options` WHERE `option_name` LIKE ('%\_transient\_%')

Don’t worry about crashing your database; WordPress will recreate transients as needed. If that still makes you nervous, don’t forget that there are WordPress plugins for almost everything out there – including managing and deleting transients.

4. Server not Available

If you’ve followed the steps above and you still can’t connect, there’s a good chance the problem will be with the host server.

Server malfunctions and overloads are difficult to pin down without access to hosting tools. If you suspect the server is the problem, the quickest way to resolve it would be to find a support number and give them a call. Contact your hosting company’s support team and give them the details of the error and let them know the steps you’ve taken to correct it.

Unless you have a dedicated server of your own, you’re probably using a shared server, which means someone else’s site could be wreaking havoc with the server, crashing your site and a dozen others. Or they may be experiencing a sudden flood of traffic the server just can’t handle. This is less likely to happen with a virtual private server or WordPress managed hosting, but the situation is what it is, and sometimes all you can do is let them know there’s a problem and wait until it gets fixed.

Managed hosting means that your server is optimized to run WordPress, but you could lose some of the other functionality as a result.

The good news is they should get right on it – uptime is valuable to your hosting company, too. If it’s a physical malfunction, there’s usually a standby or backup server that can be brought online. Often an overload will force a server reboot. If these kind of problems keep recurring, alert your host, and if they can’t remedy the problem you might want to backup your entire site and consider moving it elsewhere.

If it’s your WordPress site that keep having problems with traffic surge, you might want to look for a good caching plugin. This saves posts and pages as static files that can be served up to users, lowering demand on the server.

If the problem is on their end they should be able to identify and correct it.

For instance, user permissions might have gotten changed, so even if the password and username are right, you might not have the access you expect. You host will have to reset permissions.

Your database connection problems, however, are generally the result of human error, resulting from minor typos or changes that we don’t even remember doing, or plugins that only expert web developers can fix. If none of these measures work, you’ll have to work with your host to get issues resolved. Even starting from bare bones and a fresh wp-content and wp-config is better than losing out altogether. Hopefully, you’ve saved copies of everything, and you can re-introduce them one at a time during the rebuild. At least, in the meantime, you’re still up and running.

If none of this helps, you may have to look for help. Do keep in mind that WordPress is an open-source content management system that’s become one of the most popular in the world, with reportedly over 60 million users.

MySQL and PHP are also very widely used.

With that kind of community, when all else fails, there are tons of WordPress tutorials and forums out there.

The following two tabs change content below.

Jamie Spencer

My name is Jamie Spencer and I have spent the past 10 years building money making blogs. After growing tired of the 9-5, commuting and never seeing my family I decided that I wanted to make some changes and launched my first blog. Since then I have launched lots of successful niche blogs and after selling my survivalist blog I decided to teach other people how to do the same.

6 thoughts on “How to fix the ‘Error Establishing a Database Connection’ in WordPress”

  1. Hi Jamie,
    I clearly fudged up my website by changing the theme (I needed to add a code and knew no other way to do it). The website turned into those blue and black texts which reminded me of a website from the early 2000’s and I decided to restore everything using the latest backup. After the backup I get the Database Error message, but I can’t even login into wordpress. It’s literally the only thing that appears and I’m desperate. Is there anything I can do?
    Thanks

    Reply

Leave a Comment