Do you remember the “Blue Screen of Death” form grade school (mid 90’s). That terrible screen of blue telling you that Windows had an error and you knew all your work was gone? In the WordPress world we have the “Error Establishing Database Connection” warning. To me, it evokes the same “oh crap” feeling.

Well good news, I’m going to share with you some methods that will cut down your troubleshooting time.

 

What Does that Even Mean?

WordPress consists of two components: a MySQL database and a web server. The web server holds the files that provide your website’s styling, functionality, and CMS. This includes HTML, CSS, Javascript, and PHP.

The MySQL database is full of tables of data. This is the data that populates the styling of your website. This includes things like posts, comments, usernames, etc. Without the database, your website won’t have much content. Without the web server, your content will look like an ugly spreadsheet. If those two resources can’t speak to one another, we’ve got big problems. And that, is what occurs during a “Error Establishing Database Connection” warning.

 

Common Causes for “Error Establishing Database Connection

Some of the most common causes of the “Error Establishing Database Connection” message are the following:

  • Database login credentials have changed
  • MySQL server is unresponsive or down
  • Database has become corrupted

The most common of these, in my experience, is the third one. Generally it is the result of a newly installed plugin wreaking havoc on your setup.

 

Diagnosing: Front End vs. Back End

The first thing you’ll want to check is if the problem is persisting on the front end and the back end. You can check this by simply going to mysite.com/wp-admin and trying to access the admin dashboard. Do you still get the “Error Establishing Database Connection” warning? If you don’t, then you may be in luck as the fix might be quick and easy.

Access your site via FTP and open the wp-config.php file. Add this code near the bottom after the line that says “happy blogging”:

define('WP_ALLOW_REPAIR', true);

 

Save the changes to the wp-config.php and open a browser. Navigate to the following: mysite.com/wp-admin/maint/repair.php. You should now see this screen:

What you’re looking at is a nice feature built into WordPress version 2.9 and above that auto-repairs corrupted database tables. Note: If you’re on a version of WordPress older than 2.9 you probably have bigger issues than corrupted database tables.

Something important to note here, is that you only want to enable this functionality when you need to use it. Enabling this and leaving it is a terrible idea as it is accessible to the public. After all, it is a fallback for repairing an inaccessible busted site.

Go ahead and hit that magic button, “repair and optimize.” See if that fixed the problem. If not, move to the next section.

 

Alternate Repair Method Using phpMyAdmin

 

Sometimes, when the database is super wonky, the self repair function of WordPress won’t cut it. Luckily, there is another way to repair the database using phpMyAdmin. Here is how to do it:

1. Log into your web host cPanel and locate the phpMyAdmin module. If you have no idea what I’m talking about, look for a panel like this.

 

 

Before I go any farther, I want to make something clear. You’re database is sacred. It is fragile, it is sensitive. Anything you do to your database is permanent. There is no nifty plugin I can recommend that will magically bring back something you delete. The adage, “measure twice, cut once” applies here.

2. Within the phpMyAdmin dashboard, click “databases” at the top. If you are hosting more than 1 website, you might see multiple database names. If you are no sure which one is which, check the wp-config.php file of the site you are repairing to find the correct database name.

 

 

3. Scroll all the way to the bottom and find a check box labeled “check all.” Check the box to select all database tables (black out in picture). In the dropdown menu, select the option “optimize table.” Let phpMyAdmin do its thing, and when its done try to reload your website. If you’re still seeing “Error Establishing Database Connection”, continue to the next step.

 

Check WP-Config.php

 

Now we are going to check wp-config.php to make sure everything is in order. The reason is simple, wp-config.php tells your web server how to connect to the database. If something is wonky in this file, that would create the connection error.

Specifically, look at this part of the file:

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

 

First, check DB_USER and DB_PASSWORD. If you recently changed your username and password you will need to change them here too for the connection to work.

DB_HOST is a PHP parameter. It tells your websites where the database sever is. It is possible that your DB_HOST value is not “localhost”, like in the example. You can try to put the IP address of your database server in place of “localhost.”

If everything looks good in this file then we can conclude the error is in the actual MySQL server.

 

Checking  the MySQL Server

 

We are going to be checking to make sure our username has the right permissions to even access the database. Sometimes with shared hosting environments, permissions can be reset on accident. Create a new file and call it wtfwordpress.php.

Paste the following code into it:

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

You will want to make sure you replace your username and password in that code, otherwise this is pointless. Note: ‘root’ is your username, and you do not want to delete the quote marks. Save the file to the root directory of your WordPress installation. Open a browser and navigate to: yourwebsite.com/wtfwordpress.php. When the page loads you should see “connected successfully” if everything is in order.

If you permissions are wrong, you will get an error stating that access was denied. If this happens, call your hosting provider and ask them to resent your permissions. After that you should be good.

If you have other methods of troubleshooting the “Error Establishing Database Connection” error, comment below!