Error Establishing a Database Connection: WordPress Fix

Your entire site is replaced by one line:

Error establishing a database connection

WordPress is running fine — PHP executed, the theme loaded far enough to print this. What failed is the handshake between WordPress and MySQL. There are only four things that break that handshake, and you can rule each one in or out in under a minute.

systemctl status mysql

Cause 1: The Database Server Is Not Running

Check this first — it accounts for most sudden failures on a site that was working an hour ago.

systemctl status mysql    # or mariadb, depending on what you installed

If it reports inactive (dead) or failed, start it:

sudo systemctl start mysql

Reload your site. If it comes back, find out why the service died before calling it fixed — a crash that happened once will happen again:

sudo journalctl -u mysql -n 50 --no-pager

On small servers the answer is usually the kernel’s out-of-memory killer terminating MySQL when PHP consumed too much RAM. Confirm it:

sudo grep -i "killed process" /var/log/syslog | tail -5

If MySQL is being OOM-killed, adding swap or moving to a larger instance is the real fix. Restarting the service just resets the clock.

Cause 2: Wrong Credentials in wp-config.php

If MySQL is running, check what WordPress is trying to use. The four values live near the top of wp-config.php:

grep -E "DB_NAME|DB_USER|DB_PASSWORD|DB_HOST" wp-config.php

Do not eyeball them — test them. Connect with the exact same values:

mysql -u YOUR_DB_USER -p -h localhost YOUR_DB_NAME

Paste the password from the config when prompted. Three outcomes, three meanings:

• A mysql prompt appears — credentials are correct, so the problem is elsewhere. Skip to cause 3 or 4.
• Access denied for user — the username or password is wrong, or the user lacks rights on that database.
• Unknown database — the database name is wrong or the database no longer exists.

To fix a password mismatch, reset the user’s password in MySQL to match the config rather than the other way around:

sudo mysql -e "ALTER USER 'YOUR_DB_USER'@'localhost' IDENTIFIED BY 'the-password-from-wp-config'; FLUSH PRIVILEGES;"

DB_HOST deserves particular attention. It is localhost on most single-server setups, but managed hosts frequently use a dedicated hostname, and a value that was correct before a migration is often wrong after one.

Cause 3: Connection Limit Reached

If the site fails only at busy times and recovers on its own, you are hitting the connection ceiling rather than a configuration error. Check the limit and current usage:

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

If Threads_connected sits near max_connections, connections are not being released fast enough. On a server you control, raising the ceiling buys headroom:

sudo mysql -e "SET GLOBAL max_connections = 300;"

That change is temporary and resets on restart — make it permanent in your MySQL configuration once you have confirmed it helps. On shared hosting you cannot change this, so the fix is to reduce demand: add page caching so most visitors never touch the database, and audit plugins that query on every request.

Cause 4: Corrupted Database Tables

If MySQL is up, credentials work, and connections are fine, a corrupted table is the remaining explanation — usually after an unclean shutdown or a full disk. WordPress ships a repair tool for this. Enable it by adding one line to wp-config.php, above the line that says to stop editing:

define('WP_ALLOW_REPAIR', true);

Then visit https://yoursite.com/wp-admin/maint/repair.php in a browser and choose “Repair Database”. You do not need to be logged in, which is exactly why the next step matters.

Remove that line the moment the repair finishes. Leaving it in place lets anyone on the internet run database operations on your site.

You can also repair from the command line without touching the config:

sudo mysqlcheck --repair --all-databases -u root -p

Verify the Fix

Test the connection the same way WordPress does, using a short PHP script rather than a browser reload:

php -r '$c = new mysqli("localhost","DB_USER","DB_PASS","DB_NAME"); echo $c->connect_error ?: "connected OK\n";'

Then load both the front page and /wp-admin/. The admin area makes far more database calls, so a front page that loads while the dashboard fails points to a specific corrupted table rather than a connection problem.

Prevent It From Happening Again

Make MySQL restart itself if it dies:

sudo systemctl edit mysql

Add:

[Service]
Restart=always
RestartSec=10

Then reload systemd:

sudo systemctl daemon-reload

On servers with 1–2 GB of RAM, add swap so the OOM killer stops choosing MySQL. And keep automated database backups — the repair tool recovers table structure, but only a backup recovers lost rows.

Frequently Asked Questions