How to Fix Error Establishing a Database Connection in WordPress

Overview

This section gives you the fast mental model: what the error means, what it does not mean, and the safest first steps.

WordPress stores posts, pages, settings, users, and plugin data in a database, usually MySQL or MariaDB. When WordPress loads, it reads database details from wp-config.php and tries to connect. If that connection fails, WordPress cannot continue, so it stops and shows the database connection error.

In practical terms, the failure is usually in one of these areas:

• Incorrect database credentials: database name, username, password, or host in wp-config.php do not match the actual database settings.
• Database server is down or overloaded: the host, port, or underlying database service is not responding.
• Corrupted database tables: WordPress can reach the database, but one or more core tables are damaged.
• Hosting-level problem: account suspension, resource exhaustion, storage issues, or a broader platform outage.
• Recent change introduced the issue: migration, credential reset, plugin action, restore, or manual edits to config files.

Before changing anything, do these three checks:

1. Confirm whether the error affects both front end and wp-admin. If both fail, the issue is likely deeper than a theme or page cache problem.
2. Note any recent changes. A host move, password reset, domain change, restore, staging push, or security plugin action often points directly to the cause.
3. Take a backup if you still can. If you have hosting access, export the database and save a copy of wp-config.php before editing. If you need a broader process, see How to Back Up a Website: Files, Databases, Restore Tests, and Backup Schedules.

If the site is business-critical, also start a simple incident log: time detected, symptoms, recent changes, and each action taken. That makes recovery faster and prevents repeated guesswork.

Core framework

Use this step by step framework in order. It starts with the least destructive checks and moves toward deeper repair.

1. Check whether the issue is local to WordPress or broader hosting

Log in to your hosting control panel or server. If you cannot access the control panel, databases, or file manager at all, the problem may sit with the host rather than WordPress. Also check whether other sites on the same account are affected.

If you use uptime alerts, compare the outage time with server events. This helps distinguish a one-site misconfiguration from a broader service interruption. For a related process, see Website Uptime Monitoring Guide: What to Track and Which Alerts Matter.

2. Verify database settings in wp-config.php

Open wp-config.php in the WordPress root directory and review these values carefully:

• DB_NAME
• DB_USER
• DB_PASSWORD
• DB_HOST

Do not assume they are correct because the site worked yesterday. Passwords may have been rotated, database users may have been recreated, or a migration tool may have written a new host value.

Common patterns to check:

• Typographical errors, including invisible spaces introduced during copy and paste.
• Wrong database host. On many hosts, localhost works, but some require a specific hostname or a nonstandard port.
• Mismatched environment values. Staging credentials copied into production is a frequent cause after deployments.
• Special characters in passwords that were changed in the hosting panel but not updated in wp-config.php.

If possible, compare the config values against the database settings shown in your hosting panel instead of relying on memory.

3. Test whether the database user still has access

Even if the database name and username look correct, the user may have lost privileges. This can happen after a migration, database clone, or manual database maintenance. In the hosting panel, confirm:

• the database exists
• the user exists
• the user is assigned to that database
• the user has the expected privileges

If your host allows it, reassign the user to the database and reapply privileges. That can resolve silent permission breakage without changing WordPress itself.

4. Check whether the database server is responding

If credentials are correct but WordPress still cannot connect, the database service may be down or overloaded. Signs include:

• database tools in the hosting panel fail to load
• phpMyAdmin or similar tools time out
• multiple sites using the same database server fail together
• the host status page or support confirms a database issue

On managed hosting, this often requires host intervention. On a VPS or dedicated server, you may need to inspect the database service directly, review error logs, restart the service if appropriate, and check disk space or connection limits.

5. Determine whether the database needs repair

Sometimes WordPress can partially reach the database but finds corruption in one or more tables. A clue is an error that appears on the front end but admin pages show additional repair-related messaging, or the issue appeared after an abrupt shutdown, failed update, or storage problem.

You can enable WordPress repair mode by adding this line to wp-config.php:

define('WP_ALLOW_REPAIR', true);

Then visit:

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

Run the repair option, and when finished, remove the line from wp-config.php. Do not leave repair mode enabled longer than necessary.

If you have direct database access, you can also inspect tables through your database tool and repair only the affected ones. Be cautious with optimization or bulk repair actions on large or busy sites unless you have a current backup.

6. Review recent migrations, restores, and domain changes

If the error appeared right after moving the site, restoring from backup, or changing hosting, check the handoff points:

• Did the database import complete successfully?
• Was wp-config.php updated for the destination environment?
• Was the correct database user created on the new host?
• Did the restore overwrite a working config with old credentials?
• Did you push staging to production and carry over the wrong database reference?

Database errors often look dramatic, but they are frequently just environment mismatch problems after a move.

7. Check logs before changing more variables

If the cause is still unclear, review available logs:

• hosting error logs
• PHP error logs
• database service logs, if you manage the server
• WordPress debug output, if safely enabled

The aim is to answer a narrow question: is this an authentication failure, an unreachable host, a permissions problem, or a corrupted table problem? Once you know that, the fix is usually straightforward.

Practical examples

These examples show how the framework works in common real-world situations.

Example 1: Password changed in hosting, site not updated

A site owner resets the database user password in the hosting panel after a security scare. The site goes down minutes later with the database connection error.

What to do:

1. Open wp-config.php.
2. Compare DB_PASSWORD with the new password in the hosting panel.
3. Update the file carefully and save.
4. Reload the site and admin area.

Why this works: WordPress can only connect with the credentials stored in wp-config.php. If the host-side password changes first, WordPress keeps trying the old one.

Example 2: Staging config copied to production

After a manual deployment, production starts showing the error, but the database itself is healthy.

What to do:

1. Compare production wp-config.php with your known-good backup or deployment variables.
2. Confirm DB_NAME, DB_USER, and DB_HOST are production values.
3. Check whether salts or table prefix changes were also copied unintentionally.

Why this works: Environment drift is a common cause, especially when a deployment process handles files but not secrets consistently.

Example 3: Database server issue on shared hosting

Multiple sites on the same host account fail at once, and phpMyAdmin loads slowly or not at all.

What to do:

1. Confirm the issue affects more than one site.
2. Check the hosting dashboard for service notices.
3. Open a support ticket with exact timestamps and affected services.
4. Avoid unnecessary WordPress changes while the host investigates.

Why this works: When the database service is down, editing WordPress files usually does not help and can add confusion to the timeline.

Example 4: Corrupted tables after an interrupted update

A server runs out of resources during maintenance. Afterward, the site shows database-related failures.

What to do:

1. Take a fresh copy of the current database if possible.
2. Use WordPress repair mode or your database tool to inspect and repair affected tables.
3. If repair fails, restore from the most recent clean backup.
4. After recovery, check storage, memory, and maintenance procedures to avoid recurrence.

Why this works: Repair can help with table-level issues, but if corruption is wider, a known-good backup is safer than repeated repair attempts.

Example 5: Wrong DB_HOST after moving to a new host

A migration completes, files are present, but the new host requires a specific database hostname instead of localhost.

What to do:

1. Review the host's database connection details.
2. Update DB_HOST in wp-config.php.
3. Retest the site.

Why this works: A wrong host value blocks the connection even when the database name, user, and password are all correct.

If you are making larger site changes, it is safer to test them first on a clone. See How to Create a Staging Site for WordPress and Test Changes Safely.

Common mistakes

This section helps you avoid the troubleshooting habits that turn a short outage into a longer one.

• Editing multiple things at once. If you change credentials, repair tables, disable plugins, and restore files in one pass, you may never learn what fixed the issue.
• Skipping backups because the site is already down. A broken site can still contain recoverable data. Preserve the current state before major edits.
• Assuming the problem is a plugin. This specific error usually points to the database path, not ordinary plugin conflicts.
• Leaving repair mode enabled. Remove the repair constant after use.
• Trusting memory instead of the hosting panel. Database names and users are easy to mix up across staging and production.
• Ignoring the database host value. Many people check the name, user, and password but leave the wrong host unchanged.
• Restoring only files. A WordPress site depends on both files and database content. Partial restores can create new inconsistencies.
• Failing to document the root cause. If the outage came from a password rotation, migration checklist gap, or host-side failure, write it down and update your procedure.

After the site recovers, take five minutes to harden the process around it. Add a simple website setup checklist for migrations, credential changes, and restore tests. That single habit prevents many repeat incidents.

When to revisit

Use this section as your action list after recovery and whenever your hosting or deployment setup changes.

You should revisit this topic when:

• you migrate to a new hosting provider
• you clone staging to production or production to staging
• you rotate database credentials
• you change server architecture, containers, or managed database endpoints
• you restore from backup after an incident
• your host changes connection requirements
• you begin seeing intermittent connection drops rather than a full outage

A practical post-recovery checklist:

1. Confirm the site loads for logged-out and logged-in users.
2. Open wp-admin and test basic actions such as saving a draft, updating a setting, and loading plugins.
3. Check key site functions including forms, search, and checkout if relevant. If email delivery also broke during the incident, review How to Fix a Website Contact Form That Is Not Sending Emails.
4. Review logs for the exact failure mode.
5. Document the root cause and preventive fix.
6. Update your runbook with the correct database host, credential location, and restore order.
7. Verify backups and test a restore path.
8. Set or refine uptime alerts so the next outage is detected faster.

Finally, if the database error appeared during a broader website move or infrastructure cleanup, review nearby dependencies too. Redirect changes, HTTPS issues, sitemap availability, and crawler controls can all be affected by a rushed recovery. Related references include How to Set Up Redirects: 301 vs 302, Domain Changes, and Broken URL Fixes, How to Fix Mixed Content Errors After Enabling HTTPS, XML Sitemap Guide: How to Create, Submit, and Troubleshoot Site Maps, and robots.txt Guide for Beginners: What to Allow, Block, and Test.

The main takeaway is simple: this WordPress database connection error looks like a single message, but it represents a small set of repeatable failure points. If you check them in order—hosting availability, wp-config.php, user privileges, database health, and recent changes—you can usually restore service quickly and with less risk.