During the last couple of days my hosting provider had been having hiccups with the shared DB connections thus putting all my sites down for a few minutes from time to time. Apart from the support given by the hosting company (which is always fast and keen) this time they couldn’t figure out what was going on with the shared server, so they offered to migrate the entire setup to a new server (cool!).

It’s in these situations  that you have the opportunity to see what WordPress spits out when the DB connection is unavailable. You get a super-ugly message saying:

Error establishing a database connection

Or a card with other very useful information to your site’s visitors (from the /wp-includes/wp-db.php):

Error establishing a database connection
This either means that the username and password information in your wp-config.php file is incorrect or we can’t contact the database server at xxxx. This could mean your host’s database server is down.

  • Are you sure you have the correct username and password?
  • Are you sure that you have typed the correct hostname?
  • Are you sure that the database server is running?

If you’re unsure what these terms mean you should probably contact your host. If you still need help you can always visit the WordPress Support Forums.

These types of messages  won’t help anyone, being the site admin or the visitor, they are ugly and may disclose sensitive information.

So, what can we do to improve?

The mysterious world of drop-in’s

Fortunately WordPress allow us to write a drop-in plugin to override the default DB error page. According to the WP 3.6 core (/wp-includes/functions.php), function dead_db():

// Load custom DB error template, if present.
if ( file_exists( WP_CONTENT_DIR . '/db-error.php' ) ) {
    require_once( WP_CONTENT_DIR . '/db-error.php' );

This means we can drop-in our custom db error page in the /wp-content/ folder which eventually WP will pick up when time (hopefully, never) comes.

Here an example of a possible db-error.php file:

<?php // custom WordPress database error page
header('HTTP/1.1 503 Service Temporarily Unavailable');
header('Status: 503 Service Temporarily Unavailable');
header('Retry-After: 300');  // in seconds
<html dir="ltr" lang="en-US">
  <title>Service Temporarily Unavailable</title>
  <style type="text/css">
    body {
      margin: 6em;
    h1, p {
      font-family: Helvetica, sans-serif;
      font-size: 24px;
      color: #333;
    p {
      font-size: 14px;
  <p>Tiny unicorns took over the website to make it even more beautiful. Back in minutes!</p>

The nice thing about this solution is that it persists even during WordPress core updates, as the content directory is not affected during the upgrades.

What other drop-in’s are you using?