When you start using WordPress, you’re bound to encounter a number of errors, some grievous, other not so much. It’s inevitable; it can be your fault, at times systems break, someone fails at their job, natural calamities strike – anything could cause an error.
Even something as good as an increase in traffic can break your WordPress site, leaving you with an error and a bad taste in your mouth.
Now, just like any other human-made project, WordPress is susceptible to its share of errors, none of which is as baffling and strenuous as the “error establishing database connection” error. That’s because this error doesn’t come with details of what went wrong, despite that it can be caused by several things, which – of course – only adds salt to the wound.
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.
Why do you get this error?
Well in short, you are getting this error because WordPress is unable to establish a database connection. Now the reason why WordPress is unable to establish a database connection can vary. It could be that your database login credentials are wrong or have been changed. It could be that your database server is unresponsive. It could be that your database has been corrupted. In our experience, majority of the times this error happens because of some sort of server error however there could be other factors as well. Lets take a look at how to go about troubleshooting this problem.
3 Steps to Determine this Error Message
1. Determine where the error is occurring
Can you see your website normally, but get the error when trying to access wp-admin? Or maybe your website is down, but you’re getting a slightly different error when you try to login: “One or more database tables are unavailable. The database may need to be repaired.”
These are signs of database corruption.
WordPress has a built-in way to attempt to repair your database, but you’ll have to enable this feature first. To do so, you’ll need to access your wp-config.php file, which contains your WordPress installation settings and configuration.
You can find wp-config in the your root WordPress file directory. You can access it by logging into your control panel, selecting File Manager, and navigating to the folder where you installed WordPress.
Once you have wp-config open, add this line of code to the bottom:
define( 'WP_ALLOW_REPAIR', true );
This line will enable you to optimize and repair your database by navigating to www.yourwebsite.com/wp-admin/maint/repair.php (just replace “yourwebsite.com” with your actual URL).
You should see the above screen with two options to repair, or repair and optimize, your database. Feel free to choose either; just note that optimizing will take longer.
Please note that this database repair page is not secure; anyone can access that URL without having to login. Once you’re done repairing your database, be sure to remove the line of code you added to wp-config. This will disable access to the repair page and prevent anyone else from messing with your database.
Keep wp-config open for now until you’re certain the error is resolved and your website is working again. If you’re still getting the same error message, you’ll need wp-config open for the next step.
If this doesn’t apply to you, or if it didn’t work, move on to the next step to continue troubleshooting.
2. Check your database login settings in wp-config
If the above step didn’t work or didn’t apply to you, then the next thing you can do is take a look at your database settings in your wp-config file.
Wondering how your database login credentials could have suddently stopped working? Things like switching hosting companies or changing anything about your database name or user information could cause the error if your wp-config file wasn’t updated to the new information.
You may still have the wp-config file open from the last step. If not, log into your host’s cPanel and open the File Manager. Navigate to the directory where you installed WordPress, and look for a file called wp-config.php. Go ahead and open that for editing.
You’ll see the login credentials for your database, probably near the top of the file. It should look something like this:
// ** MySQL settings - You can get this info from your web host ** // /** The name of the database for WordPress */ define( 'DB_NAME', 'database_name_here' ); /** MySQL database username */ define( 'DB_USER', 'username_here' ); /** MySQL database password */ define( 'DB_PASSWORD', 'password_here' ); /** MySQL hostname */ define( 'DB_HOST', 'localhost' );
As you can see, there are four pieces of information WordPress needs to access your database:
- The name of the database (“DB_NAME”)
- The login username (“DB_USER”)
- The login password (“DB_PASSWORD”)
- The database host (“DB_HOST”)
If any one of these values is incorrect, WordPress will not be able to connect to the database.
One way to check on your database outside of WordPress is by using PHPMyAdmin, a tool for accessing and editing MySQL databases. PHPMyAdmin is included with most hosting plans, and you can find it in your cPanel dashboard.
Warning: Be very careful using PHPMyAdmin, since you’ll be dealing directly with your site’s database.
Once you’ve logged in to PHPMyAdmin, you will see a list of databases on your server in the left-hand column. Click on the one that matches the name in your wp-config file (it will be the value after DB_NAME, where it says “database_name_here” in the above sample code).
(Don’t see any databases? Contact your hosting company, since the entire problem may be an issue with your server.)
After clicking on your database name, you’ll see the main screen populate with the names of the tables in your database. To make sure this is the correct database, you can find the table named “wp_options” and click on the ‘Browse” option next to it. You should see your website’s name, URL, and your other general settings here. Now you know whether or not you have the correct database name in your wp-config file. If it’s not correct, go ahead and fix it in wp-config.
Now let’s check on the username and password.
There are a few ways to do this, some more convoluted than others. I’ll give you two options.
- You can either create a simple .php file to test whether you are able to connect to your database with the credentials in your wp-config file, or
- You can just create a new user and password, and update your wp-config file with the new info. You’ll have to do this if #1 fails, so you might just want to skip to this step.
Option 1: Test your existing credentials.
Create a file in your WordPress directory called something like testconnection.php (the name doesn’t matter; just the .php extension). Paste the following code:
<?php
$test Connection = mysql_connect('localhost', 'root', 'password');
if (!$testConnection) {
die('Error: ' . mysql_error());
}
echo 'Database connection working!';
mysql_close($testConnection);
?>
Once you’ve created that file, just navigate to the URL of the file in your browser (e.g. your site.com/testconnection.php). You’ll see either a successful connection message, or an error with more details.
If the username and password isn’t working, we can just create a new one.
Option 2: Create a new database user and password.
We can do that using a different tool available in cPanel called “MySQL® Databases.” Go ahead and click on that, then scroll down to the heading: MySQL Users: Add New User.” Choose a username and strong password, and make note of them for your wp-config file. Click “Create User.” Now scroll down to the heading “Add User To Database,” and choose your new username and your WordPress database, and click “Add.” Update your wp-config file with the new username and password.
Now your database name, username, and password are all correct. That just leaves DB_HOST.
3. Check your Web Host (MySQL Server)
Often you will notice this Error establishing database connection when your site gets swarmed with a lot of traffic. Basically, your host server just cannot handle the load (specially when you are on shared hosting). Your site will get really slow and for some users even output the error. So the best thing you should do is contact your hosting provider and ask them if MySQL server is responsive.
For those users who want to test if MySQL server is running yourself, you can do a few things. Test other sites on the same server to see if they are having the issue. If they are also getting the same error, then most definitely there is something wrong with your MySQL server. If you do not have any other site on this same hosting account simply go to your control panel and try to access phpMyAdmin and connect the database. If you can connect, then we need to verify if your database user has sufficient permission. Create a new file called testconnection.php and paste the following code in it:
<?php
$link = mysql_connect('localhost', 'root', 'password');
if (!$link) {
die('Could not connect: ' . mysql_error());
}
echo 'Connected successfully';
mysql_close($link);
?>Make sure to replace the username and password. If the connected successfully, then it means that your user has sufficient permission, and there is something else that is wrong. Go back to your wp-config file to make sure that everything there is correct (re-scan for typos).
If you cannot connect to the database by going to phpMyAdmin, then you know it is something with your server. It does not necessarily means that your MySQL server is down. It could mean that your user does not have sufficient permission.
