Fixing "error establishing a database connection" in WordPress

The message "Error establishing a database connection" means WordPress can't connect to its database.¹ The database holds almost everything on your site: posts, pages, comments, settings, user accounts and plugin settings. Without it, WordPress can't show anything.

It's one of the more serious WordPress errors because it affects the whole site. Visitors see the error on every page, and you usually can't reach the dashboard either.

The cause is usually one of a few things: wrong database details in your wp-config.php file, the database server being down or overloaded, damaged database tables or the database server hitting its connection limit. The fix depends on which one is responsible.

Check with your hosting provider first

Before editing anything, check your hosting provider's status page or contact their support. If the database server is down, overloaded or being maintained, there's nothing to fix on your side.

Ask whether anything has changed recently, such as maintenance, a database or PHP upgrade, a move to a different server or a change to database passwords. These are common triggers for this error, and your host can often fix them directly. They can also check the database server's logs, which you can't see.

Check your database details

A common cause is a mismatch between the database details in wp-config.php and the actual database settings on your hosting account. This can happen if the database password was 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 your WordPress root folder) via SFTP or your hosting file manager. Download a copy before you change anything, so you can put the original back if an edit makes things worse. Then check these 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 needs to match exactly what your hosting account has for your database. Most hosting control panels have a database section (often called MySQL Databases or similar) that lists the database names and users.

• DB_NAME is the name of the database. Some hosts add your account name to the front of database names, so the full name might be account_wordpress rather than just wordpress.
• DB_USER is the database username, which may have the same kind of prefix. The user also needs to be assigned to the database with the right permissions. Your control panel shows which users belong to which databases.
• DB_PASSWORD is the database user's password. If it was recently changed in your hosting panel, wp-config.php needs the new one. Your control panel usually won't show the existing password, but lets you set a new one. If you do, you'll need to put the same new password in wp-config.php, and anything else that uses that database user will need it too.
• DB_HOST is the database server's address. On many hosts it's localhost, but some use a specific hostname, IP address or port.² Your host's documentation or support team can tell you the right value. This often changes when a site moves to a new host.

wp-config.php contains your database password, so be careful where you save copies of it, and don't send it to anyone you don't trust.

Test the connection with phpMyAdmin

If you're not sure whether the database server is responding, try opening phpMyAdmin from your hosting control panel and looking at your WordPress database.

If phpMyAdmin connects and you can see your tables, the database server is working, and the problem is most likely the details in wp-config.php. Note that phpMyAdmin in a control panel usually logs in with your hosting account rather than the database user WordPress uses, so it doesn't prove the WordPress user's password is right.

If phpMyAdmin can't connect either, the database server is probably down or misconfigured. That's a hosting problem for your provider to fix.

Repair damaged database tables

Database tables can be damaged after a server crash, an unexpected shutdown, a disk problem or an interrupted write. If your database details are right and the server is running, damaged tables may be stopping WordPress from reading what it needs.

Before repairing anything, take a backup of the database. Your hosting control panel's backup tool or phpMyAdmin's Export tab will both do this. Repairs usually help, but on a badly damaged table they can lose data, and a backup is your only way back.

WordPress has a built-in repair tool, which is switched off by default. Add this 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. There's also a Repair and Optimize Database option,³ but optimising can take a long time on a large database, so the plain repair is the better choice when you're just trying to get the site back.

Anyone can use this page without logging in while the setting is on,² so remove the line from wp-config.php as soon as you've finished.

If you have SSH access and WP-CLI, wp db check reports any problems with your tables, and wp db repair attempts to fix them.⁴ The same backup advice applies.

Check database connection limits

Hosting plans often limit how many connections to the database your site can have open at once. A burst of traffic, or a plugin making an unusually large number of database queries, can hit that limit. When it does, new connections are refused and visitors see the error.

This kind of failure is usually temporary and clears as traffic drops, but if it keeps happening, ask your host whether you're hitting a connection limit and what your options are. Reviewing heavy plugins can also help.

Traffic spikes from bots and crawlers are a common trigger. Our guides to fixing 502, 503 and 504 errors and diagnosing a suddenly slow site cover finding and blocking that kind of traffic.

Check plugins and your theme

Occasionally a plugin or theme causes this error, for example by overloading the database. It's unlikely if the error appeared without any recent changes, but worth checking once you've ruled out the causes above.

Connect via SFTP or your hosting file manager, go to wp-content/plugins/ and rename plugin folders one at a time (for example, from plugin-name to plugin-name-disabled), checking the site after each. Rename them back when you've finished. You can test your theme the same way by renaming its folder in wp-content/themes/. WordPress then switches to its default theme if one is installed, so you'll need to reactivate your own theme afterwards and check your menus and widgets.

Restore from a database backup

If nothing else works and you have a recent database backup, restoring it may be the quickest way back. Most hosts offer backups you can restore from their control panel, or they can restore one for you.

Restoring replaces your current database with the backup, so anything added since it was taken (orders, form entries, comments, posts or new users) will be lost. Take a backup of the current database first, even though it isn't working, in case you need anything from it later. On a shop or membership site, talk to your host or a developer before restoring.

You can also import a database backup through phpMyAdmin's Import tab, but large backups can time out, and a failed import can leave the database half-restored. If your backup is large or you're not confident, ask your host to restore it.

After restoring the database, check your files (themes, plugins and uploads) match the same point in time. A database from a different date to your files can cause problems, such as references to plugins or images that no longer exist.

Need help with a database connection error?

Database problems can be delicate, and a wrong change can make things worse. Your hosting provider is the best first contact, since many causes are at server level. If you're not comfortable editing wp-config.php, working in phpMyAdmin or running repairs, my freelance WordPress development and emergency WordPress support services cover database recovery and configuration.