"Error establishing a database connection": the troubleshooting checklist

The site displays "Error establishing a database connection": this simply means that the application (WordPress or another CMS) can't talk to the MySQL/MariaDB server, for a reason that could lie in the database, in the configuration file, or in the server itself. It doesn't tell you which of the three.

The quickest test: is it the database or the site?

Before opening wp-config.php, try connecting from the terminal, outside the application. On Ubuntu 24.04 with Nginx and PHP-FPM:

mysqladmin ping -h 127.0.0.1 -u user -p

If the command confirms the server is alive, the database is working: the problem lies in the credentials or in the app's configuration. If the command hangs or returns a connection error, the problem is upstream: the service is down, has run out of connections, or has a disk issue. On cPanel and Plesk the same command works identically over SSH, because underneath there's always MySQL or MariaDB.

1. Credentials changed or wrong in the configuration file

This is the most frequent cause, especially after a migration or a restore from backup. Check it by trying to log in with the same credentials written in the app's file:

mysql -u user -p -h host database_name

If it responds "Access denied for user", the credentials or permissions don't match. Check the configuration file (on WordPress, wp-config.php, the DB_NAME, DB_USER, DB_PASSWORD, DB_HOST definitions) and the user's actual permissions on the database with SHOW GRANTS FOR 'user'@'host';. On cPanel the database user usually carries the cPanel account prefix; on Plesk the user should be checked under Databases → database user in the panel.

2. The database service is down

On Ubuntu 24.04:

sudo systemctl status mysql

(or mariadb if MariaDB is installed). If it shows "inactive" or "failed", try restarting with sudo systemctl start mysql and immediately check the error log for the reason it failed to start. The default path on Ubuntu/Debian packages is /var/log/mysql/error.log, set via the log_error directive in the configuration file: this is the same convention commonly used on Yum or APT installations, where the error log file location under /var/log is set with an option such as log-error=/var/log/mysqld.log in a server configuration file, and it's confirmed on real Ubuntu/MariaDB installations where the actual value of log_error is indeed /var/log/mysql/error.log. On cPanel, restart with /scripts/restartsrv_mysql; on Plesk, via Tools & Settings → Services Management.

3. Connections exhausted

If the log shows an error about too many active connections, compare the number of connections in use against the limit:

SHOW STATUS LIKE 'Threads_connected';
SHOW VARIABLES LIKE 'max_connections';

If the first value is close to or equal to the second, new connections are being refused. Identify stuck connections with SHOW PROCESSLIST; and close the unnecessary ones with KILL id;. To unblock things immediately without restarting: SET GLOBAL max_connections = 300; (this must then be made permanent in the configuration file, otherwise it's lost on restart).

4. Corrupted tables

A typical symptom in the log: a table reported as corrupted. Check this with the official tool:

mysqlcheck -u root -p --all-databases

To repair, again from the command line: mysqlcheck --repair gives command-line access to the REPAIR TABLE statement, using --databases or --all-databases to repair all the tables in one or more databases. Be careful about the storage engine, though: the REPAIR TABLE method only applies to MyISAM, ARCHIVE and CSV tables. InnoDB tables (the most common on recent installations) can't be repaired this way: if CHECK TABLE flags an InnoDB fault, you need to resort to the innodb_force_recovery option to get the server running again, as described in the official documentation.

When to repair and when to restore from backup: repair if mysqlcheck reports "OK" after the operation, or recovers the data with no obvious loss. Restore from backup instead when the repair reports lost or damaged rows, when the engine is InnoDB and not even innodb_force_recovery gets the server running stably, or when the disk hosting the data has shown signs of physical failure: in that case, persisting with repair risks overwriting the last good copy.

5. Disk space exhausted

Check with:

df -h

If the partition containing /var/lib/mysql is full, the database locks up and often stops itself to avoid worse damage. Free up space (old logs, binlogs with PURGE BINARY LOGS BEFORE, unnecessary local backups) and restart the service.

6. Wrong host: localhost versus socket

In many configurations, writing "localhost" as the host makes the connection use the Unix socket (typically /var/run/mysqld/mysqld.sock on Ubuntu), while "127.0.0.1" forces a TCP connection. If the application is configured for one and the server only responds on the other, the connection fails. Try both:

mysql -h 127.0.0.1 -u user -p
mysql -h localhost -u user -p

If only one of the two works, align the host in the app's configuration file, or correct the socket path in the pdo_mysql.default_socket and mysqli.default_socket directives in php.ini.

If the problem lies with the provider

If all the checks above come back clean and the database is still unreachable, the problem may lie with the provider (maintenance, disk full on the host side, network block). In this case it's worth opening a ticket including: the exact time the error appeared, the output of the mysqladmin ping command run from the command line, and the server or hosting plan identifier.

Final check

The problem is solved when mysqladmin ping responds positively, the site loads the homepage without errors, and the error log shows no new lines in the following minutes (sudo tail -f /var/log/mysql/error.log).