Database Connection Error in WordPress

In Running the Installer from my introductory WordPress course, I don't talk about situations you can get into where the installer won't run. There potentially many, and they can vary a lot with the different ways people can host a website nowadays, but today I want to take a look at one specific error:

Error establishing a database connection

WordPress is a web application written in PHP that stores everything in a MySQL database. If WordPress can't connect to MySQL for some reason, you'll get this error and basically nothing on the site will work on the front or back end. This is, of course, not good. Here are a few reasons you might see this error, and how to try to fix them.

  1. Your wp-config.php file is using the wrong hostname. Many inexpensive web hosts keep their MySQL servers running on the same machine as the web server (e.g. Apache), in which case you would use this code in wp-config.php:

    define('DB_HOST', 'localhost');

    If, however, you use a web host like Pair Networks (whom I recommend) or GoDaddy, the database and web servers are totally separate, in which case localhost won't work, and you could get the database connection error. In that case, you'll need to consult your hosting control panel or welcome letter to see what should go there. The code will end up looking something like this:

    define('DB_HOST', '');
  2. Your wp-config.php file is using the wrong username or password. This is pretty similar to #1, and probably pretty common among people setting up their first website. In the flurry of usernames and passwords you end up with when setting up a web hosting account for the first time, it can be hard to keep track of which ones are for what. Remember that MySQL has its own usernames and passwords, and those are nearly always different from your email username and password, which are themselves usually different from your control panel username and password. Phew!

    Therefore, check these lines in the wp-config.php file:

    define('DB_USER', 'username');
    define('DB_PASSWORD', 'password');

    and make sure that 'username' and 'password' above are what they should be.

  3. Your MySQL server has gone away, crashed, or gotten overloaded. If you're not hosting your site yourself, on a VPS or other system where you control everything, there's not much you can do about this one on your own, but it's worth acknowledging that it is another possible cause of the database connection error. This is likely the pickle you're in if the website was able to load successfully previously, and has suddenly stopped working without you having made any changes to the WordPress files.

    The only thing you can do in this situation is wait. Most of the time, in my experience, the problem is resolved in a matter of a few seconds. If it goes on longer than that, contact your hosting company and ask them what's going on with the MySQL server.

    If the database server is getting overloaded and trying to handle too many connections, you can try using a plugin that caches database queries, like DB Cache Reloaded. I talk about cache plugins in Essential Plugins 1: Cache in my course.

If you've watch the course and have ideas for sections I could expand on, or possible gotchas I've overlooked, please let me know.

Comments are closed on this post to keep spammers at bay. If you want to chime in, please email or send a tweet.