“Error establishing a database connection”
WP can't log in to its database, so no page loads. Get it back by hand first. Then add the free plugin: next time, its chat finds the cause.
Is your site down right now?
- Use your host's file manager or SFTP (a way to copy files to your host). Open wp-config.php, your site's settings file, in the main folder.
- Find the lines DB_NAME, DB_USER, DB_PASSWORD and DB_HOST. Compare the name and user with the databases page in your host's control panel.
- On that page, set a new password for that database user. Paste the same password into DB_PASSWORD, between the quote marks, and save.
- Reload your site. Still down? Open yoursite.com/wp-admin. If it says the database “may need to be repaired”, use WP's repair page below.
- Same error as before? Ask your host if their database server is up, or if your site hit a limit on your plan.
CMSHands can't be installed into a site that won't load. These steps come first.
A person approves every repair. Install it before anything breaks.
Needs WP 6.3 to 7.1 and PHP 8.0 or newer. What it installs
Needs WP 6.3 to 7.1, PHP 8.0 or newer, and an administrator login. One site per install.
The download is a plugin. Turning it on connects your site to cmshands.com and adds 3 small rescue files. Deleting the plugin removes them and everything it stored. What we send
Plugins are installed from a computer. Get the plugin here instead
- No account, no password to share
What it means
“Error establishing a database connection” means WP couldn't log in to the database that holds your posts, pages and settings, so it can't build any page.
- The password, user name or database name in wp-config.php doesn't match what your host has. This often follows a password change or a move.
- A change to wp-config.php, by hand or by a plugin, that broke one of the 4 database lines.
- Your host's database server is down, restarting, or too busy to answer.
- DB_HOST points to the wrong place. Most hosts use localhost; some give you an address of their own.
- Damaged database tables, often after a crash or a full disk. yoursite.com/wp-admin then says the database may need to be repaired.
- Your site hit a limit on your hosting plan, like too many connections at once or no disk space left.
What you see
Visitors see one line on a grey page: “Error establishing a database connection”. Every page shows it, and WP sends it with a 500 status, the code that tells browsers the server failed.
Open your dashboard (the screens you log in to at yoursite.com/wp-admin) and you may see more. WP adds that the “username and password information in your wp-config.php file is incorrect”, or that it can't reach the database server.
Your posts and pages are usually still in the database. WP can't reach them, so it can't show them.
How to find the cause
Read the 4 database lines
Open your host's file manager, or connect with SFTP (a way to copy files to and from your host). wp-config.php sits in your site's main folder, next to the wp-admin folder.
Find the lines with DB_NAME, DB_USER, DB_PASSWORD and DB_HOST. Copy the file to your computer before you change anything. It holds your database password, so never paste it into an email or a chat.
Compare them with your host
Open your host's control panel and find its databases page. In cPanel, it's MySQL Databases. Check that DB_NAME and DB_USER match the names there exactly, including any prefix.
Check that the user is added to that database, with all privileges. You can't read a password on that page. If you're not sure DB_PASSWORD is right, set a new one, as below.
Ask if the server is up
If all 4 lines match, the database server itself may be down or busy. Your host's status page or support can tell you. Ask them too whether your site hit a connection or disk limit.
Look for damaged tables
Open yoursite.com/wp-admin. If it says “One or more database tables are unavailable. The database may need to be repaired.”, the login works. The tables are the problem, not the password.
How to fix each cause by hand
A password that doesn't match
On your host's databases page, set a new password for the database user. Paste the same password into DB_PASSWORD in wp-config.php, between the quote marks. Save the file and reload your site.
A new password doesn't touch your content. Any other app that logs in with the same database user will need it too.
A wrong name, user or host
Copy the exact database name and user from your host's databases page into DB_NAME and DB_USER. For DB_HOST, most hosts use localhost. Some give you their own address on the same page or in their help pages.
Moved your site to a new host? The new database has its own name, user and password. Put those in wp-config.php, not the old host's.
Damaged tables: WP's database repair page
WP has a repair page of its own. Add define( 'WP_ALLOW_REPAIR', true ); to wp-config.php, above the line with “That's all, stop editing!”.
Open yoursite.com/wp-admin/maint/repair.php and press Repair Database. WP checks each table and repairs the ones it can.
Remove that line from wp-config.php as soon as it's done. While it's there, anyone can open the repair page without logging in.
phpMyAdmin, a database tool in most hosts' control panels, can do the same. Tick the tables, then choose Repair table from the menu below the list.
A database server that's down or full
You can't fix your host's server yourself. Your host can restart it, or tell you which limit your site hit. Tell them when the error started and what changed before it.
How to stop it coming back
If you change your database password at your host, put the new one in wp-config.php straight away.
Keep a copy of wp-config.php off your site, in a safe place. If the file gets changed, you can put the old one back. Treat it like a password.
Ask your host how often they copy your database, and how you'd get an earlier copy back. Then you know what to do before you need it.
Watch your plan's limits in your host's control panel. A full disk can stop the database, and so can too many visitors at once.
Next time
- On our test site (a WP site we run to try every task before we write about it), it found a wrong database password in wp-config.php. A person at CMSHands approved, and it put back the copy from before the change.
- We prepare the fix, and a person at CMSHands approves it before it runs. Tried on our test sites; hosts differ.
- It reads your settings and error log to find why WP can't reach its database, on sites that had CMSHands before they broke.
More it does here (2)
- It checks your site once a day on the free plan. Email alerts need your email address.
- The chat tells you in plain English what broke and what it did.
Why it won't wreck your site
- A person checks every repair. When your site is down you can't reach the chat, so a person at CMSHands approves the fix before it runs.
- It checks your pages after the fix. It loads your home page, login, dashboard and a post again before it calls the repair done.
What it won't do here
- It can't be installed into a site that is already down.A plugin needs a working dashboard to install. Get your site back with the steps above first, then add it before anything else breaks.
- A person approves every repairNothing in a repair runs until a person at CMSHands has checked it. It doesn't fix things alone overnight.
- If the rescue files are gone, it needs your SFTP loginRescue files are 3 small files the plugin adds to reach a site WP can't start. It uses the login only to put them and 2 settings files back.
- It can't fix your host's database serverA database server that's down, full or over its limits belongs to your host. Ask them about it.
Questions
What does “Error establishing a database connection” mean?
It means WP couldn't log in to the database where your posts, pages and settings live, so it can't build any page. Usually the login lines in wp-config.php don't match what your host has, or your host's database server isn't answering. Your content is usually still there. WP can't reach it until the login or the server is fixed.
How do I repair a WordPress database?
Use WP's own repair page. Add define( 'WP_ALLOW_REPAIR', true ); to wp-config.php, above the “That's all, stop editing!” line. Then open yoursite.com/wp-admin/maint/repair.php and press Repair Database. Remove the line when it's done, because the page works without a login. In phpMyAdmin, you can also tick the tables and choose Repair table.
Is my content gone when WordPress shows a database error?
Usually not. The error means WP couldn't reach the database, not that it's empty. Once the login lines match or your host's server is back, your posts and pages show again. If tables are damaged, WP's repair page can often fix them. Before you try anything big, ask your host for their latest copy of your database.
Can CMSHands repair my database connection right now?
Not if your site is already down and CMSHands isn't on it. A plugin can't be installed into a site that won't load, so get it back with the steps above first. With CMSHands on your site, it finds why WP can't reach its database and prepares the fix. A person at CMSHands approves it. Tried on our test sites; hosts differ.
Written by CMSHands team.
Be ready for the next one
- A person approves every repair
- No account, no password to share