The Database Connection Error on a WordPress Site

One line on a white page

A garden centre's owner opens the website on a Saturday morning in May, and all it shows is one line on a white page: Error establishing a database connection. No logo, no menu, no hours.

The same line appears on every page, for every visitor, and on the admin login too, so there is nothing to click.

It looks as if the whole site has gone. It has not. The pages are almost certainly intact; WordPress simply cannot reach the place where they are kept.

Where a WordPress site keeps its pages

A WordPress site has two parts. The files hold the software, the theme and the uploaded images. The database holds everything typed in: pages, posts, menus, settings, users and comments.

Every time someone visits, WordPress connects to the database, fetches the page and builds it on the spot. If it cannot connect, it has nothing to show, and it says so in that one line.

At many hosts the database runs on a separate server from the website's files. The site's own files can be perfectly healthy while the server holding its content is unavailable.

The usual causes

• Changed login details, when the database password was changed in the hosting control panel but not in WordPress's settings file.
• A busy database server, shared with many other sites and refusing new connections at peak times.
• A server that is down, for maintenance or after a fault at the host.
• A full account, where the database or the disk space has reached its limit.
• Damaged tables, after a crash or an interrupted update.
• A move to a new server, with the old database address still in the settings.

Each needs a different fix, so identify which one you are facing before anyone starts changing things.

Telling them apart

Ask what changed. A password reset, a move, an update or a new plugin in the last day points straight at the cause. A failure with no change on your side points to the host.

Watch whether it comes and goes. An error that appears for a few minutes at a time, especially at busy hours, suggests an overloaded database server; one that stays put suggests wrong details or a server that is down.

Try the admin address, the site's address followed by wp-admin. A message there about tables needing repair, instead of the connection error, means the database is reachable but damaged.

If other sites on the same hosting account show the same error, the problem almost certainly lies with the host's server rather than with one site.

What to ask the host

Hosts answer faster when the question is specific. Give the domain, the exact error, the time it started, and whether it comes and goes.

Then ask whether the database server is running, whether the account has reached a connection, size or disk limit, whether there was maintenance or a move, and whether the database address in the settings is still correct.

If the host finds damaged tables or a lost database, ask what backups they hold, from which dates, and how long a restore takes.

A worked example

A hydrovac excavation company in Kamloops runs a WordPress site with its services, photographs of jobs and a quote request form that contractors use from the road.

After the Heartbleed vulnerability in April, the office manager logged into the hosting control panel and changed every password she could find, as the host had advised.

One of them belonged to the database user. The site went down within the minute, and a contractor phoned to say so before anyone in the office noticed.

The company's developer compared the details in WordPress's settings file with those in the control panel, found the old password still in the file, and updated it. The site came straight back.

The developer then noted where the database password lives, so the next round of password changes includes the settings file, and set up a nightly database backup alongside the files.

The settings file

WordPress keeps four database details in a file called wp-config.php: the database name, the user, the password, and the database server's address, often localhost but at some hosts a separate name.

If any of the four is wrong, the connection fails with that same one-line error. Whoever changes a database password or moves the site has to update this file too.

The file also holds keys that protect logins, so it should never be sent by email or left as a copy in a public folder.

The database belongs in every backup

Many sites are backed up by copying their files, which is only half of a WordPress site. The pages, posts and settings are in the database, and a file copy does not include it.

A complete backup includes a database export taken at the same time as the files, kept somewhere other than the hosting account, and tested now and then by restoring it to a copy of the site.

Ask the host whether their backups include databases, how many days they keep, and whether you can download them. Treat the host's backups as a second line, not the only one.

While the site is down

Customers still need the phone number and the hours. Both should appear on the business's Google listing and social pages, which do not depend on the website.

A short post on the business's Facebook page saying the website is down, and how to reach you meanwhile, answers the question before customers have to call to ask it.

The counter-case

Sometimes the error is brief and entirely the host's: a database server restarted for maintenance and back within minutes. Waiting, and checking the host's status page, is the right response.

And a site owner who never touches passwords or plugins may go years without seeing it.

But when it does appear, the answer depends on the settings file, the host and the backup. Knowing who holds each before the morning it happens is what keeps the outage short.

When the error appears

1. Note the time and the exact message.
2. Ask what changed in the last day.
3. Watch whether the error comes and goes.
4. Try the admin address for a repair message.
5. Compare the settings file with the control panel.
6. Contact the host with specific questions.
7. Confirm the database is in every backup.

Step two solves more of these than any other. Many connection errors follow a deliberate change, such as a new password or a move, and whoever made it often knows the fix.

A host's planned move to another server is a related cause, and what to update and test around one is covered in when the host moves your account to a new server.

Frequently asked questions

West Coast Media Solutions Inc. provides web design, web development, hosting, digital marketing, and business consulting to organisations across Canada, drawing on more than twenty-five years in the field.