Fix "Error establishing a database connection" in WordPress

Error establishing a database connection

Common causes

• Incorrect DB_NAME, DB_USER or DB_PASSWORD in wp-config.php
• Wrong DB_HOST, such as localhost when the host requires a remote hostname, a port or a socket path
• The MySQL or MariaDB service is stopped or crashed, often after running out of memory
• Too many connections or the hosting account's database limits were reached
• Corrupted database tables
• The database user lost its privileges or the password was changed in the hosting panel

How to fix it

1. Check wp-config.php credentials. Open wp-config.php and compare DB_NAME, DB_USER, DB_PASSWORD and DB_HOST with the database details in your hosting panel. A recent password change or migration is the most common cause.
2. Test the login directly. From the server run mysql -u wp_user -p -h localhost wp_database with the same values. Access denied (1045) means wrong credentials or privileges; Can't connect (2002) means the server is down or the host or socket is wrong.
3. Make sure the database server is running. Run sudo systemctl status mysql (or mariadb). If it is stopped, start it with sudo systemctl start mysql and check journalctl -u mysql or the MySQL error log for out-of-memory or disk-full messages.
4. Try 127.0.0.1 instead of localhost. localhost makes PHP use a Unix socket, while 127.0.0.1 uses TCP. If the socket path is wrong for your PHP build, switching DB_HOST to 127.0.0.1 (or 127.0.0.1:3306) often fixes 2002 errors.
5. Grant privileges to the user. In MySQL run GRANT ALL PRIVILEGES ON wp_database.* TO 'wp_user'@'localhost'; then FLUSH PRIVILEGES;. On shared hosting, re-assign the user to the database in the control panel.
6. Repair corrupted tables. If the message mentions tables that need repairing, add define('WP_ALLOW_REPAIR', true); to wp-config.php, open /wp-admin/maint/repair.php, run the repair, then remove the line. With WP-CLI use wp db repair.

wp-config.php

define( 'DB_NAME', 'wp_database' );
define( 'DB_USER', 'wp_user' );
define( 'DB_PASSWORD', 'your-password' );
define( 'DB_HOST', '127.0.0.1' ); // or 'localhost', 'db.example.com:3306'

How to stop it happening again

• Update wp-config.php whenever you change the database password
• Monitor MySQL memory and disk space so the service is not killed
• Keep regular database backups with mysqldump or wp db export
• Use a persistent object cache or page cache to reduce database load on busy sites