How to fix “Error establishing a database connection”

WordPress shows Error establishing a database connection when it cannot connect to its MySQL or MariaDB database, so it has no content to show. The cause is almost always one of four: wrong details in wp-config.php, the database server not running, the database server out of memory, or a damaged database.

If you are visiting the site

The whole site depends on its database, so nothing loads until the owner fixes it. It is often brief, during a restart or a traffic spike; try again in a few minutes.

Narrow it down in one minute

Symptom	Likely cause	Go to
Started right after a migration or password change	Wrong details in `wp-config.php`	Step 2
Comes and goes, often at busy times	Database server running out of memory or connections	Steps 1 and 5
Every site on the server is down	Database server stopped	Step 1
`/wp-admin` says One or more database tables are unavailable	Damaged tables	Step 4

If you run the site

1. Is the database server running?

sudo systemctl status mariadb
sudo systemctl status mysql

If it has stopped, start it and find out why it stopped:

sudo systemctl start mariadb
sudo journalctl -u mariadb -n 50 --no-pager
sudo dmesg -T | grep -iE "killed process|out of memory"

A Killed process ... (mariadbd) or (mysqld) line means the server ran out of memory and the kernel stopped the database to save itself. Starting it again only fixes it until the next busy period. The lasting fixes are more memory, a swap file, fewer PHP-FPM workers so PHP leaves room for the database, or a smaller innodb_buffer_pool_size on a small server.

If the database will not start at all, its log usually says why. A full disk is a common one:

df -h

A disk at 100% stops the database from writing. Clear old logs or backups to make room.

2. Are the login details right?

Open wp-config.php and find these four lines:

define( 'DB_NAME', 'example_wp' );
define( 'DB_USER', 'example_user' );
define( 'DB_PASSWORD', 'the-password' );
define( 'DB_HOST', 'localhost' );

Test them directly, using the same values:

mysql -u example_user -p -h localhost example_wp

If you get Access denied for user, the password is wrong or the user does not have access to that database. Reset the password as the database administrator:

sudo mysql -e "ALTER USER 'example_user'@'localhost' IDENTIFIED BY 'new-strong-password';"

If Unknown database, the database name is wrong or the database was never imported. List what exists with sudo mysql -e "SHOW DATABASES;".

If the user exists but cannot use the database, grant access:

sudo mysql -e "GRANT ALL PRIVILEGES ON example_wp.* TO 'example_user'@'localhost';"

Then put the same details in wp-config.php. This step fixes most errors that appear right after moving a site to a new host, where the new server’s database details differ from the old.

On cPanel, database and user names have the account name as a prefix, such as cpuser_wp, and the user must be added to the database under MySQL Databases > Add User to Database.

3. Is DB_HOST right?

DB_HOST is usually localhost. Some hosts run the database on a separate server and give you its name in the control panel; managed cloud databases give a hostname and sometimes a port, written as db.example.net:3306.

If localhost fails but 127.0.0.1 works, MySQL is listening on the network but not on the socket file PHP expects. Use 127.0.0.1, or set the socket path in DB_HOST as localhost:/var/run/mysqld/mysqld.sock.

On AlmaLinux, Rocky and RHEL, SELinux blocks PHP from connecting to a database on another server until you allow it:

sudo setsebool -P httpd_can_network_connect_db 1

4. Is the database damaged?

If /wp-admin loads but says tables are unavailable, or the log mentions a crashed or corrupted table, check and repair:

wp db check
wp db repair

Without WP-CLI, add define( 'WP_ALLOW_REPAIR', true ); to wp-config.php, visit /wp-admin/maint/repair.php, run the repair, then remove the line, since that page works without logging in. Take a backup before repairing.

5. Too many connections

Too many connections in the logs means every connection slot was in use. Each PHP worker can hold one, so a traffic spike with many workers can exhaust the default of 151. Check the peak:

sudo mysql -e "SHOW GLOBAL STATUS LIKE 'Max_used_connections'; SHOW VARIABLES LIKE 'max_connections';"

If the peak reaches the limit, page caching is the better fix than raising the limit, since it stops most visits from touching the database at all.

6. On shared hosting

You cannot restart the database yourself. Check the control panel’s resource usage for hit limits, and check wp-config.php against the details in MySQL Databases. If the details are right and the error persists, the host’s database server is down; contact support with the time it started.

Confirm it is fixed

wp db check
curl -I https://example.com/

The first confirms WordPress can reach the database, the second that the site answers 200. If the cause was memory, watch free -h through the next busy period.