Fix "Error Establishing a Database Connection" in WordPress

“Error establishing a database connection” means WordPress’s PHP code couldn’t connect to MySQL or MariaDB — so it can’t load a single post. Every page shows the same message. On a VPS you have full access to fix it; work through these causes from most to least likely.

1. Is the database server running?

sudo systemctl status mariadb     # or: mysql

If it’s stopped or failed, find out why before restarting:

sudo journalctl -u mariadb -n 50 --no-pager
sudo tail -n 50 /var/log/mysql/error.log

Then start it:

sudo systemctl start mariadb

The most common reason it stopped: out of memory

On small servers, the Linux OOM killer terminates the biggest process when RAM runs out — usually MySQL. Check:

sudo journalctl -k | grep -i -E "out of memory|killed process"
free -h

If you see Killed process … (mariadbd) or (mysqld), the fix is to reduce memory pressure:

• Add swap as a safety net — see swap file vs partition.
• Lower innodb_buffer_pool_size and max_connections in the MySQL config.
• Reduce PHP-FPM pm.max_children so PHP can’t use all RAM.
• Find what’s causing traffic spikes (bots, a crawler, an attack) in the access log.
• Or move to a plan with more RAM.

2. Are the credentials in wp-config.php right?

grep -E "DB_(NAME|USER|PASSWORD|HOST)" /var/www/example.com/wp-config.php

Test them directly with the MySQL client, using exactly those values:

mysql -u wpuser -p -h localhost wordpress

• Access denied → the user, password or host doesn’t match. Reset the password as root:

ALTER USER 'wpuser'@'localhost' IDENTIFIED BY 'the-password-in-wp-config';

• Unknown database → the database name is wrong, or the database was never imported.

Watch for special characters in the password: a ' or \ inside the PHP string can break it. Regenerate a password without quotes if in doubt.

3. Is DB_HOST correct?

• localhost → connects via the Unix socket.
• 127.0.0.1 → connects via TCP.

These behave differently: MySQL treats 'wpuser'@'localhost' and 'wpuser'@'127.0.0.1' as separate accounts, and if MySQL’s socket is in a non-default location, PHP may not find it. If one fails, try the other. After a migration from shared hosting, DB_HOST may still point at the old host’s database server (e.g. mysql.oldhost.com) — change it to localhost.

A custom socket path can be written as localhost:/var/run/mysqld/mysqld.sock.

4. Is the PHP MySQL extension installed?

If the database works from the command line but WordPress can’t connect, check that PHP has mysqli:

php -m | grep -i mysqli

Missing? Install it and restart PHP-FPM:

sudo apt install php-mysql
sudo systemctl restart php8.3-fpm

Usually you’d see a different error (“Your PHP installation appears to be missing the MySQL extension”), but it’s worth ruling out after PHP upgrades.

5. Too many connections?

Under heavy traffic, MySQL may refuse new connections:

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

If they’re equal, either traffic exceeds capacity or queries are slow and pile up. Short-term, raise max_connections modestly; long-term, add page caching so most requests never reach PHP and MySQL. See MySQL too many connections.

6. Corrupted tables

If the error appears only in wp-admin, or the message says “One or more database tables are unavailable”, tables may need repair. Check:

sudo mysqlcheck --check wordpress
sudo mysqlcheck --repair wordpress     # MyISAM tables; InnoDB repairs itself on restart

WordPress also has a built-in repair page: add define('WP_ALLOW_REPAIR', true); to wp-config.php, visit /wp-admin/maint/repair.php, then remove the line afterwards — the page needs no login.

7. Disk full

MySQL stops writing — and may refuse to start — when the disk is full:

df -h

Free space (old backups, logs, Docker images) and restart MySQL. See disk full troubleshooting.

8. Hacked or changed wp-config.php

If credentials were changed and you didn’t do it, treat it as a possible compromise: check wp-config.php modification time (ls -l --time-style=full-iso), scan for malware, and review the WordPress malware removal steps.

Quick diagnosis script

Create a temporary file dbtest.php in the site root:

<?php
$mysqli = new mysqli('localhost', 'wpuser', 'password', 'wordpress');
echo $mysqli->connect_errno ? 'Error: ' . $mysqli->connect_error : 'Connected OK';

Open it in the browser, read the exact error, and delete the file immediately afterwards.

Prevent it from happening again

• Monitor the site with an uptime checker — see Uptime Kuma.
• Size RAM for your traffic, with swap as a buffer.
• Use page caching and an object cache to keep database load low.
• Keep daily database backups, so even corruption is a short outage — see mysqldump backups.

If memory is the recurring cause, a bigger plan is a support ticket away: WordPress VPS plans can be moved to a larger size when you need more RAM.

• WordPress
• MySQL
• Troubleshooting