Database connection error — diagnostics

Summary

The error "Error establishing a database connection" or "Connection refused" means the application cannot connect to MySQL/MariaDB. Check the service status, credentials, and server resources.

Applies to:
✔ VPS
✔ Dedicated servers
✔ MySQL, MariaDB
✔ Linux

Step 1: check MySQL/MariaDB status

systemctl status mysql

Or for MariaDB:

systemctl status mariadb

If the service is stopped:

systemctl start mysql

Step 2: check if MySQL is listening

ss -tlnp | grep 3306

Check the socket:

ls -la /var/run/mysqld/mysqld.sock

Step 3: check MySQL logs

tail -50 /var/log/mysql/error.log

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

Step 4: check credentials

Make sure the login and password in the application config match the MySQL data.

WordPress (wp-config.php):

grep -E "DB_NAME|DB_USER|DB_PASSWORD|DB_HOST" /path/to/site/wp-config.php

Test the connection manually:

mysql -u USERNAME -p DATABASE_NAME

Step 5: check disk and memory

df -h

free -m

If the disk is full, free up space:

mysql -e "PURGE BINARY LOGS BEFORE DATE(NOW() - INTERVAL 3 DAY);"

Step 6: connection limit exceeded

mysql -e "SHOW STATUS LIKE 'Threads_connected';"

mysql -e "SHOW VARIABLES LIKE 'max_connections';"

If Threads_connected is close to max_connections, increase the limit in /etc/mysql/my.cnf:

max_connections = 200

systemctl restart mysql

Step 7: repair corrupted tables

mysqlcheck -u root -p --auto-repair DATABASE_NAME

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

Verification

mysql -u root -p -e "SELECT 1;"

Expected result: a table with the number 1. Open the website and verify the error is gone.

If MySQL won't start after all checks or data is corrupted, open a support ticket. Include:
- output of systemctl status mysql
- last 50 lines of /var/log/mysql/error.log
- output of df -h and free -m