“Error establishing a database connection”: the fix

What WordPress is telling you

Error establishing a database connection

Every page WordPress builds starts with connecting to MySQL or MariaDB using four values in wp-config.php. When that connection fails, nothing else can run, so WordPress stops and prints this one line. It says the connection failed; it does not say why. The first job is to find out whether the database is unreachable or simply refusing the credentials.

If wp-admin shows a different message — “One or more database tables are unavailable. The database may need to be repaired” — WordPress did connect, and the problem is damaged tables. Skip to the repair section.

Cause 1: wrong details in wp-config.php

define( 'DB_NAME', 'shop_wp' );
define( 'DB_USER', 'shop_user' );
define( 'DB_PASSWORD', '...' );
define( 'DB_HOST', 'localhost' );

This is the usual cause right after a migration, a host change or a password reset in the hosting panel. Compare each value with the database and user listed in the control panel. Check that the user is actually assigned to that database with all privileges — creating both is not the same as linking them.

DB_HOST is not always localhost. Managed hosts often use a separate database server name, and some setups need 127.0.0.1 rather than localhost (which makes PHP use a socket file instead of TCP), or a port, as in 127.0.0.1:3307. The host’s documentation gives the right value.

Cause 2: the database server is down or out of memory

If the details have not changed and the site was working, the database server has probably stopped. On shared hosting that is the host’s problem: check their status page or open a ticket. On your own server, check it directly:

systemctl status mysql        # or mariadb
journalctl -u mysql --since "1 hour ago"
dmesg | grep -i "killed process"   # the kernel killed it for memory

On a small VPS the most common story is memory: a traffic spike or a heavy plugin pushes the server out of RAM and the kernel’s OOM killer stops MySQL, because it is the largest process. Restarting brings the site back; adding swap, lowering innodb_buffer_pool_size to fit the machine, or moving to a larger plan keeps it back.

“Too many connections” in the logs means the server is up but has run out of connection slots — usually traffic, a bot, or slow queries holding connections open. Page caching takes most of that load off the database.

Cause 3: damaged tables

A crash at the wrong moment can leave a table marked as needing repair. WordPress has a built-in repair screen, switched off by default. Add this line to wp-config.php:

define( 'WP_ALLOW_REPAIR', true );

Then visit /wp-admin/maint/repair.php and choose Repair Database. The page works without logging in — which is why you must remove the line as soon as it is done. With WP-CLI, wp db repair does the same; on the server, mysqlcheck --repair --all-databases.

A two-minute test to tell them apart

Put a file called dbtest.php in the site folder with the same four values, open it in the browser, and delete it straight after:

<?php
$link = mysqli_connect( 'localhost', 'shop_user', 'PASSWORD', 'shop_wp' );
echo $link ? 'Connected' : 'Failed: ' . mysqli_connect_error();

• “Access denied for user” — credentials or privileges: cause 1.
• “Connection refused”, “No such file or directory” or “Can’t connect to MySQL server” — the server is down, or DB_HOST is wrong: cause 1 or 2.
• “Unknown database” — DB_NAME is wrong, or the database was not imported.
• “Connected” — the details work. Check the repair screen, and that the table prefix in wp-config.php ($table_prefix) matches the imported tables.

The checklist

1. Compare DB_NAME, DB_USER, DB_PASSWORD and DB_HOST with the hosting panel; confirm the user is linked to the database.
2. Run the connection test file and read the exact error; delete the file.
3. Server down? Restart MySQL and check the logs for the OOM killer.
4. Damaged tables? Repair with WP_ALLOW_REPAIR, then remove the line.
5. After a migration, check $table_prefix matches the imported tables.