How to Fix the Error Establishing a Database Connection in WordPress

Step-by-step fix for the WordPress database connection error. Covers wp-config.php credentials, MySQL service check, WP-CLI repair, plugin conflicts, and max_connections.

Ekin Yalgın

April 27, 2025·4 min read

How to Fix the Error Establishing a Database Connection in WordPress

Seeing the Error Establishing a Database Connection screen on a production WordPress site means your server cannot communicate with the database, and every single page, post, and user session is completely dead.

Time to fix: 5 to 15 minutes
Tools needed: SSH/Terminal access, FTP/SFTP, WP-CLI
Primary causes: Corrupted database, wrong credentials, stopped MySQL/MariaDB service, PHP memory limits

Diagnosis: Is It Just the Frontend or Is wp-admin Down Too?

Before you touch any configuration files, isolate the failure. Go to yoursite.com/wp-admin. If you see the exact same generic connection error, your credentials or database server are completely offline. If you see a different message stating the database needs repair, your server is running but the tables are corrupted. This distinction saves you hours of chasing the wrong fix.

Check wp-config.php Credentials First

Your wp-config.php file acts as the master key. Even a single trailing space in the password string breaks the connection.

Test the Connection with an Independent PHP Snippet

Create a file named db-test.php in your root directory with a basic mysqli_connect call using the exact credentials from your config file. Run this from your browser. If this script connects but WordPress fails, your server is fine and the issue lies within WordPress core files or active plugins. If it also fails, you have confirmed a credential or server-level block.

Table Prefix Mismatch

Many developers overlook the $table_prefix variable. If your config file specifies wp_ but your actual MariaDB tables use wp_custom_, WordPress will act like the database is entirely empty or unreachable. Check your phpMyAdmin or terminal to verify the exact prefix in your tables and match it in the config.

DB_HOST Variations: Localhost, Sockets, and Custom Ports

Using localhost does not work on every hosting setup. Managed environments often require a specific IP address, a custom port, or a direct Unix socket path. Check your hosting provider documentation. Sometimes changing localhost to 127.0.0.1 forces a TCP connection instead of a socket and instantly resolves the block.

Server and Database Level Outages

Sometimes the database service simply crashes under heavy load. Open your terminal and run:

systemctl status mysql
# or
systemctl status mariadb

If the output shows the service as failed or inactive, restart it:

systemctl restart mysql

Exceeding max_connections on Shared Hosting

Traffic spikes can exhaust your allowed concurrent database connections. When this happens, MySQL refuses new requests from WordPress. Check your my.cnf configuration file to increase the max_connections limit, or contact your host to upgrade your resource allocation on a restrictive shared plan.

The Indirect Impact of PHP Memory Limits

A severely restricted PHP memory limit can mimic a database failure. When WordPress runs out of memory while querying massive tables, the connection drops abruptly. Increase WP_MEMORY_LIMIT in your wp-config.php:

define('WP_MEMORY_LIMIT', '256M');

Repairing a Corrupted Database

If you have SSH access, WP-CLI is your fastest diagnostic tool. Run wp db check to scan all tables for errors. If it finds corruption, immediately run wp db repair. This bypasses the web interface and executes the repair directly at the server level.

Internal Repair with WP_ALLOW_REPAIR

Add this line to your wp-config.php:

define('WP_ALLOW_REPAIR', true);

Then navigate to yoursite.com/wp-admin/maint/repair.php and click repair. Always remove this line after the process finishes, as the repair page is accessible without login credentials.

Direct REPAIR TABLE via phpMyAdmin

Log into phpMyAdmin, select your database, check all boxes next to your tables, and select Repair table from the bulk actions dropdown. This executes raw SQL repair commands directly, bypassing any PHP limitations.

Detecting Plugin and Theme Conflicts via Terminal

A rogue plugin executing thousands of bad queries will kill your database connection instantly. Use WP-CLI to isolate the culprit:

wp plugin deactivate --all

If the site comes back online, reactivate plugins one by one:

wp plugin activate plugin-name

Repeat until the connection drops again. The last plugin activated is your culprit. If you manage WordPress directly from your server, cleaning up WordPress CSS output from block editor styles is another server-side optimization worth combining with this kind of maintenance session.

If the error returns after a site migration, the most likely cause is wp-config.php still pointing to the old database host or credentials. Update DB_HOST, DB_NAME, DB_USER, and DB_PASSWORD to match the new environment and re-run the connection test.

FAQ

Frequently Asked Questions

The most common causes are wrong database credentials in wp-config.php, a stopped MySQL or MariaDB service, a corrupted database, a table prefix mismatch, or hitting the max_connections limit on shared hosting. Start by checking whether /wp-admin shows the same error or a different one — this helps narrow the root cause quickly.

Start with the safest steps first: verify credentials in wp-config.php, then run wp db check via WP-CLI. If corruption is found, use wp db repair or the built-in WP_ALLOW_REPAIR tool. These repair operations do not delete data. Only restore from backup as a last resort.

Run systemctl status mysql (or systemctl status mariadb on MariaDB servers) via SSH. If it shows failed or inactive, restart it with systemctl restart mysql. On shared hosting without SSH access, contact your host to check database server status.

Yes. A plugin executing thousands of bad queries can exhaust MySQL connections or cause memory failures that mimic a connection error. Use wp plugin deactivate --all via WP-CLI, check if the site recovers, then reactivate plugins one by one to identify the culprit.

For most setups it is localhost, but some managed hosting environments require 127.0.0.1, a custom IP, a specific port like 3306, or a Unix socket path. Check your hosting provider's documentation. Switching from localhost to 127.0.0.1 forces a TCP connection and sometimes resolves connection blocks.

After migration, wp-config.php still points to the old database host and credentials. Update DB_HOST, DB_NAME, DB_USER, and DB_PASSWORD to match the new environment. Then create a quick db-test.php file to confirm the connection works independently before testing WordPress.

Published in

Web Development