When WordPress, a popular blog publishing platform built in PHP and uses MySQL database, cannot connect or having problem connecting to the database (such as when database is down), or the MySQL server has too many connections exceeding maximum connection allowed (especially when your post or article is been dugg on Digg.com) and rejects or denies new incoming connections, WordPress will display a default “error establishing database connection” error message page. However, the WordPress error page, some is shown below, is not visitor friendly or user friendly, and worse, the default database error page also reveals the SQL server address and name.

Can’t select database

We were able to connect to the database server (which means your username and password is okay) but not able to select the localhost database.

* Are you sure it exists?
* On some systems the name of your database is prefixed with your username, so it would be like username_wordpress. Could that be the problem?

If you don’t know how to setup a database you should contact your host. If all else fails you may find help at the WordPress Support Forums.

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 localhost. 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?

These default WordPress database error pages are more meant for website administrators or webmasters rather than the public visitors.

Since WordPress 2.3.2, wp-db.php located in wp-include directory which manages the WordPress database connection introduced the support for custom database error page.

To use custom WordPress database connection error page, just upload a file called db-error.php to your wp-content directory. db-error.php file is the custom DB error template which will be loaded if present, otherwise, the default WordPress database connection error message will be shown.

Note
If you change your wp-content directory to another name or location, place db-error.php in that new path accordingly.

A simple example of db-error.php is as follow:

<?php
// Set proper HTTP header, requires PHP >= 4.0.1
$sapi_type = php_sapi_name();
if (substr($sapi_type, 0, 3) == 'cgi')
    header( 'Status: 503 Service Temporarily Unavailable' );
else
    header( 'HTTP/1.1 503 Service Temporarily Unavailable' );
header( 'Retry-After: 600' ); // 5 minutes, you don't want the site to down for too long

// Send mail to notify administrator, optional
$mailto   = "[email protected]"; // example only, change to your email address
$subject  = "Database Error at " . $_SERVER['SERVER_NAME'];
$message  = "Database connection error when someone tried to open this page:

http://" . $_SERVER['SERVER_NAME'] . $_SERVER['REQUEST_URI'];
$mailfrom = "From: WordPress"; // change to your email address or sender name

mail($mailto, $subject, $message, $mailfrom);
?>

// HTML for the error page template.
//
// It's recommended to not using get_header() and get_footer() as WordPress won't be able 
// to resolve the active theme where there is no database connection. You can view source code of
// your web page or copy the code from header.php, single.php and footer.php (after stripping out
// WordPress variables), and use the code as template.

<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
	<title>WordPress Database Error</title>
	<meta charset="utf-8" />
	<style>
	body {
		background: #fff;
		font-family: Helvetica, sans-serif;
		font-size: 18px;
		line-height: 1.3;
		padding: 20px;
		margin: 70px auto 0;
	}
	h1 {
		font-size: 32px;
		font-weight: normal;
		margin-top: 0;
	}
	p {
		margin: 10px;
	}
	</style>
</head>
<body>
	<h1>We encountered some problem!</h1>
	<p>Looks like we're unable to serve you the page right now. Administrator has been notified about the error. Please check back soon!</p>
</body>
</html>
Note
By default, WordPress will send HTTP status 500 Internal Server Error when encountering database error. We use status 503 which indicates the problem is temporary. If you prefer, you can change the header status to 500 too.

Note that if you don’t set any HTTP status code in header, WordPress will send a normal status 200 OK header, which means that the web pages may be erroneously indexed an error page as its content.

Legacy Method for Very Old Versions of WordPress - For Reference Only
You can change the error page to another different error page by modifying or altering wordings and text in the error page by customizing the wp-db.php file located in wp-include directory. Here’s how you can hack the WordPress default error message.

In wp-db.php (the file that handles the database connections that WordPress makes), you can see lines like “DB Constructor – connects to the server and selects a database” and “Select a DB (if another one needs to be selected)”. That’s where you can alter the text and word in the error page. Just look carefully after the line, you will see exactly the some text and message as appeared on the database error page. Edit them to your liking.

Wordpress Bail Function

Beside, from line 312 onwards is the header and footer output for the HTML of database connection error page, contains inside function named “bail”, which specifies things like the title of “WordPress: Error”. The “bail” function is called whenever a database connection error is encountered, and does what it’s name said – bails out the error and displays an error message instead to notify the users. You can change them if you like too.

Please take a backup of wp-db.php file before you customize or alter it. If you break the code, your website visitors and surfers will get the PHP error instead. Beside, be careful that when you upgrade your WordPress. If you overwrite all files when upgrade the WordPress, the wp-db.php will be replaced back with the original unchanged version too, and you have to edit the file again. Else, backup the wp-db.php before upgrading your WordPress and restore it after upgrading is done.

You May Also Interested In: