How to Fix Database Connection Errors

The "Error Establishing a Database Connection" message means WordPress cannot connect to its MySQL database. This is one of the most common WordPress errors and has several possible causes.

Understanding the Error

WordPress needs a MySQL database for all dynamic content — posts, pages, settings, users, and more. When the connection fails, the entire site goes down. The error can appear on the front end, the admin area, or both.

Step 1: Verify wp-config.php Credentials

The most common cause is incorrect database credentials in wp-config.php.

1. Open cPanel > File Manager
2. Navigate to your WordPress root directory (usually public_html)
3. Open wp-config.php and find these lines:

define( 'DB_NAME', 'your_database_name' );
define( 'DB_USER', 'your_database_user' );
define( 'DB_PASSWORD', 'your_database_password' );
define( 'DB_HOST', 'localhost' );

Cross-Check with cPanel

1. Go to cPanel > Databases > MySQL Databases
2. Verify that:
   • The database name listed matches DB_NAME (including the cPanel prefix, e.g., username_wpdb)
   • The database user matches DB_USER
   • The user is added to the database with All Privileges
3. If the password might be wrong, change the user's password in cPanel and update wp-config.php to match

Test with phpMyAdmin

1. Go to cPanel > phpMyAdmin
2. Try to access the database
3. If it loads and shows your WordPress tables, the database itself is fine — the issue is the credentials in wp-config.php

Step 2: Check MySQL Server Status

Shared Hosting

On shared hosting, MySQL is managed by BearHost. If MySQL is down:

1. Try accessing phpMyAdmin — if it also fails, MySQL may be temporarily down
2. Check the BearHost status page for any ongoing incidents
3. Contact support — the team can restart MySQL if needed

VPS or Dedicated Server

If you manage your own server:

sudo systemctl status mysql
sudo systemctl status mariadb

If MySQL is stopped:

sudo systemctl start mysql

Check the MySQL error log for why it stopped:

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

Common reasons: out of memory (OOM killer), disk full, or too many connections.

Step 3: Repair Corrupted Database Tables

Corrupted tables can prevent WordPress from reading the database.

WordPress Built-In Repair

Add this to wp-config.php (temporarily):

define( 'WP_ALLOW_REPAIR', true );

Then visit: https://yourdomain.com/wp-admin/maint/repair.php

Click Repair Database or Repair and Optimize Database.

Important: Remove the WP_ALLOW_REPAIR line from wp-config.php immediately after, as this page is accessible without login.

Via phpMyAdmin

1. Open phpMyAdmin
2. Select your WordPress database
3. Click Check All to select all tables
4. From the dropdown at the bottom, select Repair table
5. Then select all tables again and choose Optimize table

Via Command Line (VPS)

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

Step 4: Check Disk Space

If the server disk is full, MySQL cannot write data and crashes:

df -h

On shared hosting, check your disk usage in cPanel's sidebar. If you are at or near your limit:

1. Clean up old backups, logs, and email
2. Empty the trash in cPanel File Manager
3. Run sudo apt autoremove && sudo apt clean on VPS

Step 5: Check DB_HOST Setting

DB_HOST is usually localhost, but some configurations require variations:

| Setting | When to Use | |---|---| | localhost | Standard shared and VPS hosting (default) | | 127.0.0.1 | If localhost does not work (forces TCP instead of socket) | | localhost:/path/to/mysql.sock | Custom socket path | | remote-hostname | External database server |

If localhost is not working, try 127.0.0.1. If your database is on a separate server, use that server's hostname or IP.

Step 6: Connection Limit Issues

Too many simultaneous database connections can exhaust the limit:

Shared Hosting

• Each cPanel account has a maximum number of MySQL connections (usually 25–50)
• High traffic, bad plugins, or stuck processes can exhaust this
• Install a caching plugin to reduce database queries per page load

VPS

Check and increase the limit in MySQL configuration:

sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

max_connections = 150

sudo systemctl restart mysql

Step 7: Restore from Backup

If nothing else works, restore your database from a backup:

1. cPanel JetBackup: Go to JetBackup > Database Backups > select a date > Restore
2. cPanel Backup Wizard: Restore a previously downloaded backup
3. UpdraftPlus: If you have the plugin configured, restore from the plugin interface
4. Manual: Import a SQL dump via phpMyAdmin

Diagnostic Checklist

| Check | Status | Fix | |---|---|---| | DB_NAME matches cPanel? | | Update wp-config.php | | DB_USER matches cPanel? | | Update wp-config.php | | DB_PASSWORD correct? | | Reset in cPanel, update wp-config.php | | User added to database? | | Add in MySQL Databases | | phpMyAdmin accessible? | | MySQL may be down — contact support | | Tables corrupted? | | Run repair via phpMyAdmin or WP repair mode | | Disk space available? | | Clean up files, increase storage | | DB_HOST correct? | | Try localhost or 127.0.0.1 | | Connection limit hit? | | Enable caching, reduce concurrent queries |

Preventing Future Database Errors

• Regular backups: Enable automatic daily backups
• Monitor disk space: Set up alerts before disk fills up
• Use caching: Reduce direct database queries with a caching plugin
• Optimise database: Clean and optimise monthly with WP-Optimize
• Keep credentials documented: Store a copy of your database credentials in a password manager
• Update WordPress safely: Always back up before updating core, plugins, or themes