TechCorner HQ · Technical Troubleshooting Guide

WordPress Error Establishing a Database Connection: Causes and How to Fix It

By TechCorner HQ Editorial Desk Last reviewed Review standards

If your WordPress website displays "Error establishing a database connection," the PHP execution layer and web server are operational, but WordPress cannot successfully open a communication session with its MySQL or MariaDB database backend. Unlike network-edge proxy timeouts explained in Cloudflare Error 522 (Connection Timed Out): Causes and How to Fix It, this failure originates entirely on the hosting infrastructure hosting the application and database.

To restore your site quickly without risking data loss, resolve the failure by determining whether the root cause is credential mismatches in wp-config.php, unavailable database daemon processes, user permission deficiencies, or table corruption.

Primary Root Causes

  • Incorrect Connection Constants: Values assigned to DB_NAME, DB_USER, DB_PASSWORD, or DB_HOST in wp-config.php do not match the database environment on your hosting server.
  • Unresponsive Database Service: The MySQL/MariaDB server daemon has stopped running, crashed due to system resource exhaustion, or saturated its connection limits.
  • Database Table Corruption: Specific storage tables within the database have become inconsistent due to ungraceful server terminations or failed writes.
  • Insufficient User Permissions: The database user defined in the configuration lacks privileges (such as SELECT, INSERT, UPDATE, and DELETE) on the designated database schema.

Diagnostic Sequence

  1. Visit yourdomain.com/wp-admin to inspect whether the administrative backend returns the exact same connection error or reports unavailable database tables.
  2. Access your hosting control panel database tool (such as phpMyAdmin) to establish whether the MySQL service itself is responsive.
  3. Inspect wp-config.php to compare defined database credentials directly against the database name and authorized users in your hosting control panel.
  4. Verify database user assignments and privilege grants.
  5. Run repair routines if the database daemon is running but individual tables are inaccessible.

Step-by-Step Resolution Procedures

Warning: Always create a full backup of your website files and database before modifying server configuration files or executing database repair routines.

1. Compare wp-config.php Constants to Server Settings

Open wp-config.php in your site's root directory using SFTP or your host's file manager. WordPress manages database connectivity via defined constants:

define( 'DB_NAME', 'database_name_here' );
define( 'DB_USER', 'username_here' );
define( 'DB_PASSWORD', 'password_here' );
define( 'DB_HOST', 'localhost' );

Check every character inside single quotes:

  • Ensure there are no leading or trailing whitespace characters accidentally pasted into the credentials.
  • Confirm the DB_HOST setting. While localhost is standard, some hosting platforms isolate database services onto separate internal hostnames or IP addresses (sometimes requiring custom ports, such as 127.0.0.1:3306).
  • Check your hosting control panel to verify that the database assigned to DB_NAME actually exists and that the user defined in DB_USER is linked to that specific database with full data privileges.

2. Check Database Service Availability via Host Tools

Attempt to sign in to your host's database management tool (such as phpMyAdmin or a command-line shell). If the database interface returns a connection timeout or refusal, the database daemon (MySQL/MariaDB) is offline on your server. Contact your hosting support provider or restart the MySQL service via your server management dashboard.

3. Run the Built-In WordPress Database Repair Tool

If visiting yourdomain.com/wp-admin produces an error stating that one or more database tables are unavailable, WordPress can attempt an automatic repair. According to the official WordPress documentation for wp-config.php, you can enable this tool by adding the following line immediately above /* That's all, stop editing! Happy publishing. */:

define( 'WP_ALLOW_REPAIR', true );

Once added, open your browser and navigate to:

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

Click Repair Database or Repair and Optimize Database to allow WordPress to scan and reconstruct damaged tables.

Warning: When WP_ALLOW_REPAIR is set to true, the repair script does not require authentication because locked or corrupt tables often prevent users from logging in. Anyone visiting the URL can trigger repairs. Remove the define( 'WP_ALLOW_REPAIR', true ); line from wp-config.php as soon as the repair finishes.

Verification

After applying credential corrections or repair procedures:

  1. Launch a private or incognito browsing window to test the public front-end of the site without cached session tokens.
  2. Log in to the administration dashboard at /wp-admin to confirm authenticated queries and dashboard widgets load normally.
  3. Inspect wp-config.php to confirm that temporary definitions such as WP_ALLOW_REPAIR have been removed.

Sources & References