How to Fix WordPress Database Connection Errors: Complete Guide

WordPress database connection errors are among the most frustrating issues a site owner can face, and knowing how to fix them quickly can mean the difference between minutes of downtime and hours of lost traffic. When WordPress cannot connect to its MySQL or MariaDB database, visitors see the dreaded "Error Establishing a Database Connection" message instead of your content. This guide walks you through every proven fix, from checking credentials to repairing corrupted tables.

Understanding Why WordPress Database Connection Errors Happen

Before you start making changes, it helps to understand what causes this error. WordPress needs four pieces of information to talk to its database: the database name, username, password, and host. If any one of these is wrong — or if the database server itself is unavailable — the connection fails.

Common Root Causes

• Incorrect database credentials in wp-config.php
• Corrupted database tables caused by a crash or bad update
• Database server is down or overloaded on your hosting provider
• Exceeded database connection limits on shared hosting plans
• Wrong database host value (not always localhost)
• Misconfigured file permissions preventing WordPress from reading wp-config.php

How to Confirm It Is a Database Error

Visit your site's frontend. If you see "Error Establishing a Database Connection," the problem is almost certainly database-related. Also visit yoursite.com/wp-admin. If the admin area shows a different or more specific message such as "One or more database tables are unavailable," the credentials are fine but the tables are corrupted.

Step 1 — Check and Fix Your wp-config.php Credentials

The very first thing to verify is whether the database credentials stored in wp-config.php match what your hosting provider has set up. A single typo here causes the entire site to go offline.

Locating wp-config.php

Connect to your server using FTP, SFTP, or your host's File Manager. The file sits in the root of your WordPress installation — the same folder that contains wp-login.php and the wp-content directory.

Verifying the Four Key Constants

1. Open wp-config.php in a text editor.
2. Locate the four database constants shown below and note their current values.
3. Log in to your hosting control panel (cPanel, Plesk, etc.) and open MySQL Databases.
4. Confirm that the database name, username, and password listed there match what is in wp-config.php exactly — including upper and lower case.
5. Check the host value. On most shared hosts it is localhost, but some providers use a socket path or a remote hostname like db5.example.com. Consult your host's documentation if unsure.
6. Save the file and reload your site.

// wp-config.php — database connection constants
define( 'DB_NAME',     'your_database_name' );
define( 'DB_USER',     'your_database_user' );
define( 'DB_PASSWORD', 'your_database_password' );
define( 'DB_HOST',     'localhost' );

Resetting the Database Password

If the password has been changed at the server level but not updated in wp-config.php, go to MySQL Databases > MySQL Users in cPanel, set a new password, and update the DB_PASSWORD line in wp-config.php to match.

Step 2 — Repair Corrupted Database Tables

If your credentials are correct but you still see the error — or the wp-admin message says tables are unavailable — one or more database tables may be corrupted. WordPress has a built-in repair tool that you can activate with a single line in wp-config.php.

Using WordPress's Built-In Repair Tool

1. Open wp-config.php and add the following line just before the comment that reads "That's all, stop editing!"
2. Save and upload the file.
3. Navigate to yoursite.com/wp-admin/maint/repair.php in your browser.
4. Click Repair Database. WordPress will scan and attempt to fix all core tables.
5. Once the repair is complete, remove the line you added from wp-config.php immediately, because leaving it active is a security risk.

// Add this line to wp-config.php TEMPORARILY — remove after repair
define( 'WP_ALLOW_REPAIR', true );

Repairing Tables via phpMyAdmin

If the repair script does not resolve the issue, log in to phpMyAdmin through your hosting panel, select your WordPress database, check all tables, and choose Repair table from the "With selected" dropdown at the bottom of the page. This runs a lower-level REPAIR TABLE SQL command on each table.

Repairing Tables via WP-CLI

If you have SSH access, WP-CLI provides the fastest way to repair the database without touching a browser.

# Check database for errors
wp db check

# Repair all database tables
wp db repair

Step 3 — Check Whether the Database Server Is Running

Sometimes the problem has nothing to do with your files. The MySQL or MariaDB service on the server may have crashed or been temporarily suspended by your host.

On Shared Hosting

Contact your hosting provider's support team and ask them to confirm that the MySQL service is running and that your database account has not been suspended. Many shared hosts impose connection limits, and a traffic spike can exhaust them.

On a VPS or Dedicated Server

1. SSH into your server.
2. Check whether MySQL is running with the command below.
3. If the service is stopped, start it and monitor error logs at /var/log/mysql/error.log to find the underlying cause.

# Check MySQL service status (Ubuntu/Debian)
sudo systemctl status mysql

# Start MySQL if it is stopped
sudo systemctl start mysql

# Check MariaDB instead if that is your database engine
sudo systemctl status mariadb
sudo systemctl start mariadb

Checking Database Connection Limits

On shared hosting, exceeding the maximum allowed simultaneous connections produces a connection error even when credentials are correct. Installing a persistent object cache such as Redis or Memcached dramatically reduces the number of database connections WordPress needs per page load. Contact your host about increasing connection limits if this is a recurring problem.

Step 4 — Verify File Permissions and Ownership

Incorrect file permissions can prevent PHP from reading wp-config.php, which produces a database connection error as a secondary symptom.

Recommended Permission Settings

• wp-config.php — 600 or 640 (owner readable, not world-readable)
• WordPress directory — 755
• PHP files — 644

Fixing Permissions via SSH

1. SSH into your server and navigate to your WordPress root directory.
2. Run the commands below to set correct permissions.
3. Reload your site to confirm the error is resolved.

# Set correct ownership (replace www-data with your web server user)
sudo chown -R www-data:www-data /var/www/html/

# Set directory permissions
find /var/www/html/ -type d -exec chmod 755 {} \;

# Set file permissions
find /var/www/html/ -type f -exec chmod 644 {} \;

# Secure wp-config.php
chmod 600 /var/www/html/wp-config.php

Step 5 — Advanced Troubleshooting and Prevention

If none of the steps above have resolved the error, it is time to dig deeper. The following techniques cover edge cases that trip up even experienced developers.

Test the Database Connection Manually

Create a temporary PHP file in your WordPress root directory to test whether PHP can reach the database with the credentials from wp-config.php. Upload the file, visit it in a browser, then delete it immediately afterward.

<?php
$link = mysqli_connect(
    'localhost',          // DB_HOST
    'your_database_user', // DB_USER
    'your_password',      // DB_PASSWORD
    'your_database_name'  // DB_NAME
);
if ( ! $link ) {
    die( 'Connection failed: ' . mysqli_connect_error() );
}
echo 'Database connection successful!';
mysqli_close( $link );

Check for a Misconfigured DB_HOST

Some managed hosting platforms (WP Engine, Kinsta, Cloudways) use a custom socket or IP address for DB_HOST rather than localhost. Log in to your hosting dashboard, look for database details, and copy the exact host string provided. Paste it into the DB_HOST constant in wp-config.php.

Review PHP and MySQL Error Logs

Enable WordPress debug logging temporarily to capture more detail. Add the following to wp-config.php, reproduce the error, then check wp-content/debug.log for clues. Remove these lines once you have identified the problem.

define( 'WP_DEBUG',         true  );
define( 'WP_DEBUG_LOG',     true  );
define( 'WP_DEBUG_DISPLAY', false );

Prevention Best Practices

• Schedule automated daily database backups using a plugin such as UpdraftPlus or via cron.
• Use a staging environment to test plugin and theme updates before pushing to production.
• Monitor your site with an uptime tool that alerts you the moment a database error occurs.
• Keep WordPress core, plugins, and PHP versions up to date to avoid known database incompatibilities.
• Install an object cache (Redis/Memcached) to reduce database load on high-traffic sites.

Frequently Asked Questions

What does "Error Establishing a Database Connection" mean in WordPress?

It means WordPress was unable to connect to the MySQL or MariaDB database that stores your site's content. The most common reasons are incorrect credentials in wp-config.php, a stopped database server, corrupted tables, or exceeded connection limits on shared hosting.

Can I fix the WordPress database connection error without losing my data?

Yes. In most cases the data is still intact — WordPress simply cannot reach it. Correcting the credentials in wp-config.php or repairing corrupted tables restores access without deleting anything. Always take a full backup before making any changes, just in case.

Why does the database connection error keep coming back on my site?

Recurring errors usually point to a resource problem: your hosting plan may have a low connection limit that gets exhausted during traffic spikes, or your server is running low on memory and MySQL crashes periodically. Upgrading your hosting plan, installing an object cache, or optimising slow database queries typically resolves persistent issues.

How do I find my database credentials on cPanel hosting?

Log in to cPanel and click MySQL Databases. Your database name and associated username are listed there. Passwords are not displayed for security reasons, but you can set a new password from the same screen and then update wp-config.php to match the new value.

Fixing WordPress database connection errors is straightforward once you work through the checklist systematically — verify credentials, repair tables, confirm the server is running, and check permissions. For site owners who want a faster, hands-free approach to these and other WordPress tasks, WP AI Agent lets you diagnose and resolve issues like database connection errors simply by describing the problem in natural-language chat, making complex WordPress management accessible to everyone.