“Error Establishing a Database Connection” is something you don’t want to see on your WordPress site. You have probably seen this message if you’re familiar with WordPress because it’s a pretty common problem, but it can be a real disaster when you get this message on your site for the first time. It sounds frightening to a less trained user. On top of that, you don’t have a clue about what’s wrong except that it’s something to do with connecting to the database!
This post aims to provide a detailed and user-friendly algorithm for WordPress users (especially beginners) who face the “Error Establishing a Database Connection” message. No matter if you have dealt with such an issue or not, I strongly recommend bookmarking this post. Anytime you face this problem, you will be able to review and apply the following steps.
Roll up your sleeves, and let’s see how to resolve your database connection errors.
How a WordPress Site Functions
The “Error Establishing a Database Connection” message is generated by an error inside of your website’s files.
PHP and MySQL are behind any WordPress site. PHP is a widely used programming language, and it’s in charge of a site’s functions (displaying posts and pages, posting and managing comments, etc.). My SQL is a database management system that stores a WordPress site’s items. When you visit a web page, PHP connects to the MySQL database and displays the required items. The “Error Establishing a Database Connection” happens when MySQL can’t find the information required by a PHP command.
How to Resolve the Error
Try to remember if you recently installed new plugins or themes, wrote some CSS lines, or did some fine-tuning adjustments on your site. You are probably the culprit if you have. In this case, follow the next steps to resolve this issue.
If you haven’t made any changes recently, contact your hosting providers support team. The chances are that the host encountered a problem, and your site might be unavailable due to its issues. Or maybe your latest post went viral and caused a traffic spike that overloaded the server.
1. Repair the Database
I suggest you follow the exact steps of this process to save time. Start by repairing your site’s database. WordPress comes with a built-in option to repair the database. Do you know about it? Go to cPanel -> File Manager -> Home Directory -> public_html and search for wp-config.php. Open it and add the following line of code:
define( ‘WP_ALLOW_REPAIR’, true );
Next, visit www.yoursite.com/wp-admin/maint/repair.php (of course, replace yoursite with your site’s name), and you should see the message below (repair database or repair and optimise database):
Chose any of these two options (the first one takes less time) and visit your homepage. Is it working? Regardless of the result, go back to wp-config.php and delete the line of code you added previously. Do NOT ignore this step because it’s a security breach; if you leave it, a hacker could manipulate your site’s database.
2. Check Themes and Plugins
Your latest theme and plugin installs and updates could generate the awe-inspiring message. Test if any of them is guilty of your site’s unavailability.
Connect to your site files via an FTP/SFTP client. Check out this tutorial if you don’t know how to do it. Go to the public_html folder (its name may slightly vary depending on the host) and identify the wp_content folder.
Open it up, and you will see your plugins and themes folders. Change the name of the plugins folder to whatever you want and check to see if your site is still displaying the same message. Undo the name modification if the problem persists because it’s not generated by a plugin.
If your site is online, your next task is to identify the plugin responsible for the error. Rename each folder within the plugins folder manually; for example, rename wordpress-seo as _wordpress-seo. Next, individually take each plugin folder and change it back to the original name; for instance, _wordpress-seo back to wordpress-seo. Check the site. If it’s online, then yoast isn’t the culprit. At some point, a plugin rename will generate the error, and that’s the one responsible for the error.
The same algorithm can be applied to the themes folder.
3. Check Database
Another common issue that generates “Error Establishing a Database Connection” is the use of the wrong credentials to access the database. The credentials might be changed because you moved some files or changed the host. Don’t worry, resolving this problem isn’t rocket science.
Go to your site’s wp-config.php file and identify this sequence of code:
define(‘DB_NAME’, ‘some_db’);
define(‘DB_USER’, ‘some_username’);
define(‘DB_PASSWORD’, ‘some_pass’);
define(‘DB_HOST’, ‘localhost’);
‘some_db’, ‘some_username’, and ‘some_pass’ will be your database name, username, and password. Depending on your host, ‘localhost’ might have a slightly different name.
The simplest solution is to contact your hosts support team and ask to check your credentials.
Once you get the correct credentials, edit the wp-config.php file and update the credentials.
Save it and check your site.
Another solution is to use PhpMyAdmin to compare the data against the credentials in the wp-config.php file.
Head to the PhpMyAdmin interface via your hosts control panel and identify your database in the upper left part. Depending on your situation, there might be many databases, and you could be confused. Open a database, search for the wp_options table, and click on it and check the siteURL column (see the image below). If it’s the proper URL, then you have identified the correct database.
Update the name of the database in the wp-config.php file.
Next, check the username and password.
Create a new file in the root directory, name it whatever you want, and paste the following lines of code into it:
<?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);
Let’s suppose that you name the file test.php. yourdomain.com/test.php and check your site; if you still get an error message, you have to create a new username and password.
Head to your cPanel and search for MySQL Databases. Click on it, and start creating a new user with full privileges. Update the wp-config.php file and test your site again. Does it still show the same frightening message? Delete the test.php file and check the next step.
Hints
- Some hosting providers might have different interfaces. For instance, creating a new user might be a little bit different than described here. In this situation, check out the host’s FAQ page or ask a customer support agent.
- Create a backup copy before making any changes to the wp-config.php file.
- Consider asking a support agent for the database name, username, and password if the above confuses you. You could make the situation worse if making a mistake when manipulating the site’s files.
4. Restore the Default WordPress Files
Another way of fixing this issue is to replace the WordPress installation with a fresh download from the official website. Download WordPress, unzip it, and delete the wp-config.php file and wp-content folder (it stores themes, plugins, and media).
Make a backup copy. Do not skip this step!
Next, upload the WordPress files to the root directory via an FTP/SFTP client and replace your initial files. I hope that your site is now up and running! If it is still not working, contact a support agent and let them know what you have done. Most likely, there is something on the server that created your site’s malfunction.
I hope that you won’t ever need to use the steps above because your site will run night and day! However, look through all the steps and don’t forget to bookmark this post—it will be gold when you face the dreaded “Error Establishing a Database Connection.”
