Fixing "Error Establishing a Database Connection" in WordPress

"Error establishing a database connection" means one thing: PHP asked the database server for a connection using the four values in wp-config.php, and did not get one. WordPress keeps every post, page, user and setting in that database, so it has nothing to show and stops.

Only a handful of things cause it. The login details are wrong, the server is not answering, the server is refusing new connections because it is full, or the tables behind the connection are damaged. The work is to find out which of these you have before changing anything, and then to apply the one fix that matches.

Check whether the error is constant or intermittent

Reload the site a few times over a couple of minutes, and try /wp-admin/ as well.

The error is there on every load. Something is wrong and staying wrong: a changed password, a wrong host name, a database user that lost access to the database, or a database server that has stopped. It usually begins right after a migration, a password reset in the control panel or a restore.

The error comes and goes. The settings are right, because they work part of the time. The database server is running out of something: connections, memory or disk space.

One more variant: if /wp-admin/ says "One or more database tables are unavailable. The database may need to be repaired", the connection itself works and a table is damaged. Go straight to the repair section below.

The MySQL error behind "Error establishing a database connection"

The WordPress screen hides the reason. The database server gave PHP a specific error number, and there are two ways to read it.

With SSH and WP-CLI, run a check that uses the credentials from wp-config.php:

wp db check

A list of tables marked "OK" means the credentials and the server are fine right now, which points to an intermittent cause. If the command fails, its first line of output is the MySQL error.

Without SSH, switch on logging in wp-config.php by setting WP_DEBUG and WP_DEBUG_LOG to true and WP_DEBUG_DISPLAY to false. Reload the site once and read the end of wp-content/debug.log. With debugging on, WordPress stops suppressing the warning from the connection attempt, so the number lands in the log.

Error number	What it means	Where to look
1045	Access denied: wrong user name or password	DB_USER, DB_PASSWORD
1044	The user exists but has no rights on this database	User privileges in the hosting panel
1049	Unknown database: no database with that name on this server	DB_NAME
2002, 2003, 2005	The server cannot be reached: wrong host, or the service is stopped	DB_HOST, then the server
1040, 1203	Too many connections, for the server or for your user	Load and connection limits

Check the four values in wp-config.php

Download a copy of wp-config.php before you edit it. The file holds the database password and the security keys, and a stray quote in it takes the whole site down.

define( 'DB_NAME', 'your_database' );
define( 'DB_USER', 'your_user' );
define( 'DB_PASSWORD', 'your_password' );
define( 'DB_HOST', 'localhost' );

Compare each value with what the hosting panel shows in its database section.

• Name and user. Shared hosts usually put the account name in front of both, as in account_dbname. After a move to a new account the prefix changes and the old values match nothing.
• Password. Resetting the database user's password in the panel does not update wp-config.php. If in doubt, set a new one in the panel and paste it into the file. Avoid single quotes and backslashes in it, because they break the PHP string unless escaped.
• Host. localhost is right when the database runs on the same machine as the site. Managed and cloud hosts often run it on a separate server and list a host name in the panel. A custom port or a socket path goes in the same constant, for example define( 'DB_HOST', '127.0.0.1:3307' );. The wp-config.php reference shows each form.
• The link between user and database. Creating a user is not enough. It has to be added to the database with full privileges, and that link is often missing after a restore or a move (error 1044).

If the site shows the WordPress installation screen where you expected an error, the connection works but WordPress cannot find its tables. Check DB_NAME and the $table_prefix line, and do not run the installer.

When the database server is down or out of room

An unreachable server with the correct host name means the database service is not answering. On shared or managed hosting you cannot restart it yourself. Check the host's status page, then open a ticket and ask whether the database service is running and whether your database or disk is over quota.

On a server you manage, look before you restart. The service is called mysql, mysqld or mariadb depending on the system:

sudo systemctl status mariadb
df -h
sudo journalctl -u mariadb --since "1 hour ago"

A full disk and a process killed for lack of memory are the two usual findings. Free the space or the memory first, then start the service. A database that keeps getting killed is on a server too small for the work.

Why the error comes and goes under load

Every PHP request that loads WordPress holds one database connection while it runs. The server accepts a fixed number at once (max_connections), and shared hosts add a lower cap per account. When requests get slow, connections pile up until the server refuses the next one. Visitors see the error for a few seconds or minutes, and then the site recovers.

Raising the limit is rarely the answer. Find what is holding the connections:

• No page cache. Without one, every visit runs PHP and a set of queries, bots included. See how the layers of WordPress caching fit together.
• Slow queries. One slow query on a large table keeps its connection busy. Ask the host for the slow query log, or enable it on your own server.
• Automated traffic. Bursts of requests to wp-login.php or xmlrpc.php, or an aggressive crawler, show up in the access log at the same minute as the errors.
• Scheduled jobs that overlap. A backup, a product import and a feed sync starting at the same hour compete for the same connections.

If the site is cached, the queries are reasonable and the errors continue, it has outgrown the plan. Establishing that takes performance work on the queries and the server, not guesswork with limits.

Repair damaged tables with WP_ALLOW_REPAIR

Tables get damaged when the server crashes or the disk fills up in the middle of a write. WordPress ships a repair screen that is switched off by default.

1. Export the database first, even in its damaged state, with the host's backup tool, phpMyAdmin or wp db export before-repair.sql. The MySQL manual warns that a table repair can lose data in some circumstances.
2. Add define( 'WP_ALLOW_REPAIR', true ); to wp-config.php.
3. Open /wp-admin/maint/repair.php on your domain and choose "Repair Database". The second button also optimizes the tables and takes longer.
4. Read the result for every table.
5. Remove the line from wp-config.php at once. While it is present, the repair page works for anyone, logged in or not.

WP-CLI does the same job with wp db repair. Know the limit of both tools: MySQL's repair command works on MyISAM tables, which older sites still have. Tables created on current MySQL and MariaDB versions use InnoDB, which recovers from its own log when the server restarts and cannot be repaired this way. If an InnoDB table is reported as corrupt, stop experimenting and restore it from the last good backup. This is the moment you find out whether you have backups you can restore from.

Fix it yourself or ask for help

Wrong credentials and a wrong host are yours to fix with the hosting panel and ten careful minutes. A stopped database on shared hosting belongs to the host. Bring in a developer when the error is intermittent and tied to load, because that takes query and server analysis. Do the same when an InnoDB table is corrupt, when the error appeared right after a move to a new host and the obvious values look right, or when nobody is sure a current backup exists. Our WordPress maintenance service covers this kind of diagnosis, along with monitoring that reports an outage before a customer does.

Frequently asked questions

Does this error mean my content is gone?

Almost never. The posts, orders and users are still in the database. The site just cannot reach them. The exception is a damaged table, and a repair or a restore of that one table normally brings the data back.

Can visitors see something better than the bare error?

Yes. If a file named db-error.php exists in wp-content, WordPress loads it in place of the default message. Keep it to plain HTML with no WordPress functions, since the database is unavailable when it runs, and have it send a 503 status header so search engines treat the outage as temporary.

Should the database host be localhost or 127.0.0.1?

Use the value your host gives you. On a server you run yourself, localhost connects through a local socket file and 127.0.0.1 connects over the network stack, so if one fails with a connection error it is reasonable to test the other.

Will restoring a backup fix the error?

Only when the cause is damaged data. If the credentials are wrong or the server is down, a restore fixes nothing and overwrites every order, comment and edit made since the backup. Diagnose first.