Fixing "error establishing a database connection" in WordPress

The message "Error establishing a database connection" means WordPress is unable to connect to its MySQL database. The database stores all of your site's content, including posts, pages, comments, settings, user accounts and plugin configurations. Without a working database connection, WordPress can't load anything at all.

This is one of the more serious WordPress errors because it affects your entire site rather than a single page. Visitors will see the error message on every page, and you won't be able to access the WordPress dashboard either.

The cause is almost always one of a few things: incorrect database credentials in your wp-config.php file, the MySQL server being down or overloaded, corrupted database tables or the database server reaching its connection limit. The fix depends on which of these is responsible.

Check your hosting and MySQL status first

Before editing any files, check your hosting provider's status page or contact their support team. If the MySQL server is down, overloaded or undergoing maintenance, there's nothing you can fix from your end.

Ask your host whether anything has changed recently, such as server maintenance, a PHP or MySQL version upgrade, a migration to a different server or any changes to database access credentials. These are common triggers for this error that can only be resolved by the hosting provider.

Verify your database credentials

The most common cause of this error is a mismatch between the database credentials stored in your wp-config.php file and the actual database settings on your server. This can happen if credentials were changed in the hosting control panel without updating wp-config.php, or if the file was overwritten during a migration or restore.

Open wp-config.php (in the root of your WordPress installation) via FTP, SFTP or your hosting file manager and check the following four values:

define('DB_NAME', 'your_database_name');
define('DB_USER', 'your_database_user');
define('DB_PASSWORD', 'your_database_password');
define('DB_HOST', 'localhost');

Each of these needs to match exactly what your hosting control panel shows for your database. Log into your hosting control panel and find the database management section (usually under MySQL Databases or similar) to confirm the correct values.

DB_NAME is the name of the database. Make sure it includes any prefix your host adds automatically. Some hosting providers prepend your account username to database names, so the full name might be something like account_wordpress rather than just wordpress.

DB_USER is the database username. Again, this may include a prefix. The user also needs to be assigned to the correct database with the right privileges. Check your hosting panel to confirm the user is associated with the database listed in DB_NAME.

DB_PASSWORD is the password for the database user. If you recently changed the database user's password in your hosting panel, you'll need to update this value in wp-config.php to match.

DB_HOST is the hostname of the database server. On many hosting providers this is simply localhost, but some hosts require a specific IP address, hostname or port number instead. Check your hosting provider's documentation or ask their support team for the correct value. This is a particularly common issue after migrating a site to a different host.

Test the connection via phpMyAdmin

If you're not sure whether the credentials are correct or whether the database server is responding, try logging into phpMyAdmin from your hosting control panel and viewing your WordPress database tables.

If phpMyAdmin connects successfully and you can see your tables, the database server is working and the problem is most likely a credentials mismatch in wp-config.php. Compare the credentials phpMyAdmin is using (visible in your hosting panel) with what's in your config file.

If phpMyAdmin also can't connect, the MySQL server is likely down or misconfigured. This is a hosting-level issue that your provider will need to resolve.

Repair corrupted database tables

Database tables can become corrupted after a server crash, an unexpected shutdown, a disk error or an interrupted write operation. If your credentials are correct and the MySQL server is running, corruption may be preventing WordPress from reading the tables it needs.

WordPress has a built-in database repair tool, but it's disabled by default. Add the following line to wp-config.php:

define('WP_ALLOW_REPAIR', true);

Then visit https://example.com/wp-admin/maint/repair.php (replacing example.com with your domain) and click Repair Database. You can also choose "Repair and Optimize" to optimise the tables at the same time, which can help with performance.

This page does not require you to be logged in, which is why the feature is disabled by default. Remove the line from wp-config.php as soon as you've finished the repair.

If you have SSH access and WP-CLI installed, you can also check your database from the command line:

wp db check

This will report which tables, if any, are corrupted, and you can then run wp db repair to fix them.

Check database connection limits

Shared hosting plans typically limit the number of simultaneous database connections your site can make. If your site receives a traffic spike, or if a plugin is making an unusually high number of database queries, this limit can be reached. When it is, new connections (including your own attempts to load the site) are refused.

This type of failure is usually temporary and resolves itself as connections close, but if it's happening regularly you may need to talk to your hosting provider about increasing your connection limit or upgrading to a plan with more resources. Reviewing your plugins for any that are known to be database-heavy can also help reduce the load.

Check plugins and themes

In rare cases, a plugin or theme can cause this error by overwhelming the database with queries or by interfering with how WordPress establishes its database connection. This is unlikely to be the cause if the error appeared suddenly without any recent changes, but it's worth checking if you've ruled out the more common causes above.

Connect via FTP or your hosting file manager and navigate to wp-content/plugins/. Rename each plugin folder one at a time (for example, change plugin-name to plugin-name-disabled) and check whether the error clears after each one.

To test whether a theme is involved, rename your active theme's folder inside wp-content/themes/. WordPress will fall back to a default theme if one is installed.

Restore from a database backup

If none of the above has resolved the error and you have a recent database backup, restoring it may be the most straightforward path. Most hosting providers offer automatic backups that you can restore from their control panel.

If you need to restore manually, you can import a database backup through phpMyAdmin. Open phpMyAdmin, select your WordPress database, go to the Import tab and upload your backup file. Be aware that this will overwrite the current database contents, so make sure you've backed up the current state first, even if it's not working correctly.

After restoring a database backup, make sure your WordPress files (themes, plugins, uploads) match the state they were in when the backup was taken. A database backup from a different point in time than your current files can cause inconsistencies, such as references to plugins or content that no longer exist on the file system.

Need help with a database connection error?

Database issues can be delicate, and an incorrect change can make the problem worse. If you're not comfortable editing wp-config.php, working in phpMyAdmin or running database repairs, my emergency WordPress support service covers database recovery and configuration.