All Forces

This is a quick tutorial on how to have WordPress show a custom error page when there’s a database connection error. This tutorial covers WordPress 2.0.1.

The database connection error occurs when WordPress tries o connect to the database but does not succeed at it. When you are first installing WordPress, it can mean that your settings are incorrect. i.e. the username/password are wrong. However, if your WordPress installation is running smoothly but for some reason MySQL goes down on your server then WordPress will show that huge “WordPress, Error Establishing a Database Connection” error page that looks nothing like the rest of your site. The error page is great when you are first setting up WordPress but it is not the most ideal for a professional website. It creates confusion for the visitor that might not even know what WordPress is. What’s worst, the web developer might not even find out for hours.

We’re going to solve this by doing a very small hack to WordPress that will tell it to show a static page instead of the default WordPress page. And we’ll also have it send an email to the administrator alerting with the error. Don’t get scared away by the word hack. Hacking is part of the WordPress culture and even encouraged. And besides, a hack is the only way around this because plugins are detected by settings stored in the database that we can not access to begin with.

STEP 1: Hack WordPress

Note: If you are running WordPress 2.0.1 you can download the hacked file here and just replace original ‘/wp-includes/wp-db.php’ and skip to step 2.

Open ‘wp-includes/wp-db.php’ in a code editor. If you don’t have one, you can try the free Text Wrangler or my favorite, SKEdit. This file is the one that handles the database connections that WordPress makes. We’ll look at the last function around line 305. This function is called bail and it is called when a database connection error is found. It does what it’s name implies, it bails out and displays an error. Now, the error it shows follows up but before it gets to that point, we’ll have it show a custom page we created and have it email us the error found. Enter the code bellow as pictured above.

/* custom error page hack
shows a custom error page and emails error instead of
showing the default wordpress database error page */

/* end custom error page hack */

The code Explained

include('wp-content/themes/themename/dbase-error.php');
This tells it to include the page dbase-error.php located in your theme folder. Replace the themename with the folder name of your theme.

$error = ( !$this->show_errors ) ? '' : $this->show_errors ;
mail('webmaster@domain.com', 'WordPress Error', $error);
This emails the webmaster with the actual database error if there is one. Replace webmaster@domain.com with the email address of the webmaster.

die;
This tells the script to end and not execute anything further, like the default error it normally outputs.

STEP 2: Create the error page.

Create a custom error page that contains no WordPress code, name it ‘dbase-error.php’ and save it in your theme folder.

The whole point of this tutorial is for you to have an error page that looks like the rest of your site. But that really depends on what theme you use. In this example I started by duplicating ‘index.php’ from my theme folder and naming it ‘dbase-error.php’. Then I replaced the header, sidebar and footer code with the actual code found in the header, sidebar and footer. To do this, first open ‘header.php’ in a text editor, copy all it’s content and paste in ‘dase-error.php’ replacing < ?php get_header(); ?>. Do the same for the sidebar and footer.

Now proceed to remove all WordPress code since WordPress does not have access to your database it doesn’t know the website name or what theme to use. To help you out, I’ve included a custom error page for the default WordPress template. You can download it here and just change a few things like the website name and description. Pictured below is the one I used on the Mosaic site.

STEP 3: TEST

To test this, there’s no other way than to put your site down temporarily. First upload the new wp-db.php file then the new custom error page. Now, edit ‘wp-config.php’ so that it has the wrong database name and upload the file. Once you upload the edited config file, check your site through your browser. You should now see your new error page and receive a new email shortly alerting you there was a database error. Your can re-edit the config file and re-upload to bring your site back up.

CONCLUSION

Hopefully WordPress will create an easier way to do this, perhaps by including a new setting in the settings file. But for now, hacking it is our best choice. But do remember, when you upgrade WordPress for the next version you will need to reapply the hack.

FILES USED:

WordPress Hack
Custom Error