Fix WordPress "Error establishing a database connection"

What happened

You open your WordPress site and hit one line instead of your homepage: Error establishing a database connection. The admin panel at /wp-admin shows the same thing. WordPress can't reach MySQL — but the cause could be any of six different things, ranging from a typo in a config file to a crashed database engine.

Work through the steps below in order. Most sites are back online by Step 2.

Step 1 — Check wp-config.php credentials

This is the culprit roughly 70% of the time. Someone changed the database password, migrated the site to a new server, or cloned it to a staging environment and never updated the credentials in wp-config.php.

nano /var/www/html/wp-config.php

Find these four lines:

define( 'DB_NAME',     'your_database_name' );
define( 'DB_USER',     'your_db_user' );
define( 'DB_PASSWORD', 'your_db_password' );
define( 'DB_HOST',     'localhost' );

Don't guess — test the credentials directly from the shell:

mysql -u your_db_user -p -h localhost your_database_name

If MySQL rejects the login, the credentials are wrong. Either update wp-config.php to match what's in MySQL, or reset the MySQL user password:

mysql -u root -p
ALTER USER 'your_db_user'@'localhost' IDENTIFIED BY 'new_password';
FLUSH PRIVILEGES;

Then set DB_PASSWORD in wp-config.php to that same new password.

Step 2 — Verify MySQL is actually running

Correct credentials, error still there? MySQL might be down.

# Ubuntu/Debian
systemctl status mysql

# CentOS/RHEL
systemctl status mysqld

Stopped? Start it:

systemctl start mysql
# or for MariaDB
systemctl start mariadb

If it refuses to start, read the logs before doing anything else:

journalctl -u mysql -n 50 --no-pager
# or
tail -n 100 /var/log/mysql/error.log

Three startup failures show up constantly: disk full (MySQL needs space to write temp files), InnoDB crash recovery required (look for "InnoDB: Database was not shut down normally"), or a corrupted ibdata1 file. The log will tell you which one — fix that first.

Step 3 — Confirm the database and user exist

Once you're logged into MySQL, verify both the database and the user are actually there. It sounds obvious, but a botched migration or accidental DROP can wipe either one.

mysql -u root -p

-- Check the database exists
SHOW DATABASES LIKE 'your_database_name';

-- Check the user exists with the right host
SELECT user, host FROM mysql.user WHERE user = 'your_db_user';

-- Check the user has privileges on that database
SHOW GRANTS FOR 'your_db_user'@'localhost';

User exists but no grants? That's the problem:

GRANT ALL PRIVILEGES ON your_database_name.* TO 'your_db_user'@'localhost';
FLUSH PRIVILEGES;

If the database itself is gone, restore from a backup — WordPress can't create its own database from scratch.

Step 4 — Check DB_HOST value

On some setups, localhost doesn't resolve correctly. This catches people by surprise on Docker environments, managed cloud databases (Amazon RDS, PlanetScale), and some cPanel hosts where MySQL listens on a socket rather than a TCP port.

-- Find the socket path
SHOW VARIABLES LIKE 'socket';
-- Common output: /var/run/mysqld/mysqld.sock

Try changing DB_HOST in wp-config.php to one of these alternatives:

// Force TCP instead of socket
define( 'DB_HOST', '127.0.0.1' );

// Explicit socket path
define( 'DB_HOST', 'localhost:/var/run/mysqld/mysqld.sock' );

// Remote host (separate DB server or Docker container)
define( 'DB_HOST', '10.0.0.5' );

Step 5 — Repair corrupted tables

Here's an odd scenario: WordPress connects to MySQL fine, but the front page still shows the error while /wp-admin loads (or shows a different database error). Corrupted WordPress tables are usually the cause.

Add one line temporarily to wp-config.php:

define( 'WP_ALLOW_REPAIR', true );

Then open this URL in your browser:

https://yoursite.com/wp-admin/maint/repair.php

Click "Repair Database" and wait. When it finishes, remove the WP_ALLOW_REPAIR line immediately — it lets anyone trigger a repair without logging in, which is a real security exposure.

Prefer the command line? Same result:

mysqlcheck -u root -p --repair your_database_name

Step 6 — Check max_connections and disk space

High-traffic sites hit this one. MySQL has a hard cap on simultaneous connections (default: 151). When that cap is reached, new connections fail with the same error WordPress shows.

mysql -u root -p -e "SHOW STATUS LIKE 'Max_used_connections';"
mysql -u root -p -e "SHOW VARIABLES LIKE 'max_connections';"

If Max_used_connections equals max_connections, you've been hitting the wall. Bump it live without a restart:

mysql -u root -p -e "SET GLOBAL max_connections = 300;"

To make it stick across reboots, edit /etc/mysql/mysql.conf.d/mysqld.cnf:

[mysqld]
max_connections = 300

While you're at it, check disk space. MySQL silently refuses to write when the partition is full, and WordPress interprets that as a connection failure:

df -h

Any partition above 90% is worth investigating before moving on.

Verification

After applying any fix, confirm things are actually working:

• Reload the homepage — the site should come up normally.
• Open /wp-admin and log in to confirm the dashboard loads.
• Run a quick PHP connectivity test:

<?php
$link = mysqli_connect('localhost', 'your_db_user', 'your_db_password', 'your_database_name');
if (!$link) {
    echo 'Connect failed: ' . mysqli_connect_error();
} else {
    echo 'Connected successfully';
    mysqli_close($link);
}

Save this as test-db.php in your web root, visit it in a browser, then delete it right away. Never leave a raw connectivity test file sitting on a production server.

Lessons learned

• Migrating a WordPress site? Update wp-config.php credentials before importing the database — not after you've already gotten the error.
• This error is completely silent until a user hits the site. A basic uptime check (UptimeRobot has a free tier, or a cron job pinging the homepage every 5 minutes) catches it in seconds instead of hours.
• Automated MySQL backups turn a corrupted-table incident into a 10-minute restore. Without one, manual repair can stretch into hours of recovery work.
• On shared hosting and none of this works? Call your host. They routinely throttle database connections or rotate credentials without any notification to customers.