How to Fix Error Establishing a Database Connection in WordPress (5 Steps)

What Causes the WordPress Database Connection Error?

WordPress relies entirely on PHP communicating with MySQL over TCP/socket connections to pull site titles, post content, active theme settings, and user credentials. If authentication fails, the database daemon crashes due to memory exhaustion, or table indexes become corrupted, WordPress cannot render any HTML and serves the emergency error screen.

Step 1: Check Database Credentials in wp-config.php

Open your root wp-config.php file via cPanel File Manager or SSH and inspect the four database constants:

// ** MySQL settings - You can get this info from your web host ** //
define( 'DB_NAME', 'cpanelfree_wpdb' );
define( 'DB_USER', 'cpanelfree_wpuser' );
define( 'DB_PASSWORD', 'SecurePassword123!' );
define( 'DB_HOST', 'localhost' );

Common Pitfall: In cPanel, database and user names are prefixed with your account username (e.g. cpanelfree_dbname). Ensure the prefix is included in wp-config.php.

Step 2: Test Database Login via Linux Terminal / phpMyAdmin

Test if MySQL accepts the credentials defined in wp-config.php:

mysql -u cpanelfree_wpuser -p'SecurePassword123!' -h localhost cpanelfree_wpdb

If access is denied, re-assign user permissions in cPanel under MySQL Databases > Add User to Database with ALL PRIVILEGES.

Step 3: Verify MySQL Server Daemon Status

On cloud VPS or dedicated servers, verify that the MySQL/MariaDB process has not crashed due to memory exhaustion:

sudo systemctl status mariadb  # or sudo systemctl status mysql
sudo systemctl restart mariadb

Step 4: Repair Corrupted Tables with Native WordPress Repair

If the error displays “One or more database tables are unavailable” in /wp-admin/, enable WordPress repair mode by adding this line to wp-config.php right above “That’s all, stop editing!”:

define('WP_ALLOW_REPAIR', true);

Navigate in your browser to https://yourdomain.com/wp-admin/maint/repair.php and click Repair and Optimize Database. (Remember to remove the line from wp-config.php once complete to prevent public access).

Step 5: Check Free Disk Space and Memory Swapping

A full hard drive or exhausted RAM pool prevents MySQL from writing temporary tables or PID lock files. Check available disk space:

df -h
free -m

Diagnosing Remote Database Connections and Host Firewall Locks

If your WordPress website connects to a remote managed database cluster (such as AWS RDS, DigitalOcean Managed Database, or a secondary VPS), verify that the database server allows connections from your web server’s public IP address:

# Test remote database TCP port 3306 reachability
nc -zv remote-db-ip 3306

# Test direct remote authentication
mysql -u remote_wpuser -p -h remote-db-ip remote_wpdb

If the connection hangs, add an allow rule in the database server firewall (UFW: sudo ufw allow from WEB_SERVER_IP to any port 3306) and update bind-address = 0.0.0.0 in my.cnf.

Troubleshooting WordPress Table Prefix Mismatches ($table_prefix)

When migrating WordPress between hosts or restoring database backups, check that the table prefix declared in wp-config.php matches the actual table names in your database:

$table_prefix = 'wp_';  // Ensure this matches tables like wp_posts or wp_options

If your database contains custom prefixes like wp7a_posts while wp-config.php specifies wp_, WordPress will assume the database is uninstalled and display connection error screens.

Automating Database Health Recovery via Systemd Watchdog

To prevent database connection errors from taking your website offline during temporary traffic surges, configure a systemd service watchdog to automatically restart MariaDB if it ever encounters a crash:

# Create systemd override configuration
sudo systemctl edit mariadb

# Add automated restart directive
[Service]
Restart=always
RestartSec=5s

Reload systemd daemons: sudo systemctl daemon-reload. This guarantees that even if a runaway query exhausts memory, MySQL restarts automatically in under 5 seconds.

Frequently Asked Questions

Fixing MySQL Corrupted ibdata1 and Tablespace Mismatches

If WordPress displays connection errors and MySQL error logs show Tablespace is missing for table, verify that table .ibd files in /var/lib/mysql/dbname/ match the table definitions. If an orphaned tablespace exists, execute ALTER TABLE tablename DISCARD TABLESPACE; followed by ALTER TABLE tablename IMPORT TABLESPACE; to re-link data files.