How to Fix Error Establishing a Database Connection

“Error establishing a database connection” means WordPress could not log in to its database. There are only four real causes: the login details in wp-config.php are wrong, the database server is not running, the database server is running but refusing new connections, or the database itself is damaged. One test tells you which: try the same login by hand from the command line. If it works, WordPress is misconfigured. If it fails, the error message it prints names the cause.

This guide works through the causes in order of how often they happen, with the command to confirm each one and the fix. It covers both a VPS, where you have SSH, and shared hosting with cPanel, where you do not.

Step 1: Read the login details WordPress is using#

Everything WordPress knows about its database is in four lines of wp-config.php, in the site’s main folder:

grep -E "DB_(NAME|USER|PASSWORD|HOST)" wp-config.php

define( 'DB_NAME', 'shop_wp' );
define( 'DB_USER', 'shop_user' );
define( 'DB_PASSWORD', 'the-password' );
define( 'DB_HOST', 'localhost' );

On shared hosting, open the file in cPanel’s File Manager instead. Keep these four values in front of you for the next step.

Step 2: Try the same login by hand#

With SSH access, use exactly those values:

mysql -u shop_user -p -h localhost shop_wp -e "SELECT 1;"

Type the password when asked. What happens next tells you which section to read:

Without SSH, use cPanel’s phpMyAdmin: if it opens and shows your database’s tables, the server is running and the cause is the login details.

Cause 1: Wrong details in wp-config.php#

This is by far the most common cause, especially after a site has been moved, restored or had its password changed. Fix each value against the source of truth, the database server itself.

On cPanel: open MySQL Databases. Check three things, because all three are needed:

1. The database exists, with the exact name in DB_NAME, including the account prefix (account_wp, not wp).
2. The user exists, with the exact name in DB_USER.
3. Under Add User To Database, that user is attached to that database with All Privileges. A user that exists but is not attached is the classic cause after a migration.

If you are not sure of the password, set a new one for the user on the same page and put it in wp-config.php.

On a VPS: log in as the database administrator and check or reset the same things:

sudo mariadb -e "SHOW DATABASES; SELECT user, host FROM mysql.user;"
sudo mariadb -e "ALTER USER 'shop_user'@'localhost' IDENTIFIED BY 'a-new-long-password';"
sudo mariadb -e "GRANT ALL PRIVILEGES ON shop_wp.* TO 'shop_user'@'localhost';"

About DB_HOST: it is localhost on almost every server where the database and the site share a machine. If your host gave you a different name, such as a separate database server, use exactly that. If localhost fails with a socket error while the server is running, try 127.0.0.1, which connects over the network path instead of the socket file.

Cause 2: The database server is not running#

sudo systemctl status mariadb --no-pager | head -5

Use mysql in place of mariadb if that is what you run. If it says inactive or failed, start it and then find out why it stopped, or it will stop again:

sudo systemctl start mariadb
sudo journalctl -u mariadb -n 40 --no-pager
sudo journalctl -k --since "2 days ago" | grep -iE "out of memory|killed process"
df -h /var/lib/mysql

Those three checks cover the usual reasons:

• Killed for memory. A line such as Out of memory: Killed process 1234 (mariadbd) means the server ran out of RAM and the kernel stopped the largest process, which is nearly always the database. This is the most common cause on a small VPS. Our guides to adding swap space and tuning MariaDB for low RAM fix it properly.
• Disk full. At 100%, the database cannot write and shuts down. Free space first (sudo journalctl --vacuum-size=200M, old backups, old logs), then start it.
• A configuration error. If the log mentions an unknown variable or a file it cannot read, the last edit to a file under /etc/mysql/ is the cause. Undo it.

On shared hosting you cannot start the server yourself. If phpMyAdmin will not open either, the database server is down for everyone on that machine: contact your host.

Cause 3: The server is up but refusing connections#

If the error comes and goes, and appears mostly at busy times, the database has reached its connection limit. Check how close it gets:

sudo mariadb -e "SHOW VARIABLES LIKE 'max_connections'; SHOW GLOBAL STATUS LIKE 'Max_used_connections';"

If the two numbers are equal, the limit has been hit. Raising it is rarely the right fix: each connection uses memory, and the real problem is usually too many PHP workers for the server, or slow queries holding connections open. Set PHP-FPM’s pm.max_children below the database’s limit, as described in how to optimize PHP-FPM workers, and put a page cache in front of the site so most visits never reach the database at all.

On shared hosting the limit belongs to your plan. A site that hits it regularly has outgrown the plan, or has a plugin or a bot making far more requests than visitors do.

Cause 4: The login works, but WordPress still fails#

If the test in step 2 succeeds and the site still shows the error, check these in order:

• You tested a different file. Make sure the wp-config.php you read is the one the live site uses. A copy one folder up is also picked up by WordPress.
• Damaged tables. Open /wp-admin/. If it says “One or more database tables are unavailable”, add this line to wp-config.php, visit /wp-admin/maint/repair.php, run the repair, and remove the line afterwards, because that page needs no login:

  define( 'WP_ALLOW_REPAIR', true );

  With SSH and WP-CLI, wp db check and wp db repair do the same.

• A wrong table prefix. If $table_prefix in wp-config.php does not match the tables in the database (wp_ versus wpx7_), WordPress connects, finds nothing, and offers to install itself or shows this error.
• A cached error page. If the database was down for a minute, a page cache or CDN may still be serving the error. Clear the cache and test in a private window.

Stop it happening again#

• Watch the site from outside. A free uptime monitor that checks the home page every few minutes tells you before your customers do.
• Give the database room. On a VPS, add swap and size MariaDB and PHP-FPM so their combined peak fits in RAM.
• Keep a database backup you have tested. If the cause is ever corruption, a restore is the fix. See how to back up MariaDB and PostgreSQL on a VPS.
• Write the details down when you move a site. Database name, user, password and host are the four things that change, and the four things this error is about.

Common mistakes to avoid#

• Reinstalling WordPress. The error is about the connection, not the files. A reinstall changes nothing and risks your content.
• Creating a new database user and forgetting to attach it to the database. The user can log in and still sees nothing.
• Leaving WP_ALLOW_REPAIR switched on. Anyone can open the repair page while it is.
• Restarting the database every time without reading the log. If it was killed for memory once, it will be again.
• Raising max_connections to a huge number. The server then runs out of memory instead, which is worse.

Hosting where the database is looked after#

On SiteHarbour WordPress hosting, the database server is managed for you: LiteSpeed servers, NVMe storage, automated backups and built-in security hardening in every plan, with support from people who can see the server’s side of an error like this one. If you would rather run your own, a VPS gives you the reserved memory a database needs, and our engineers size its settings for your plan at setup.

Frequently asked questions#

Does this error mean my data is lost?#

Almost never. It means WordPress cannot reach the database. In nearly every case the data is intact and the site returns as soon as the connection is fixed.

Why does the error come and go?#

An intermittent error points to the server, not the settings: the database is being restarted after running out of memory, or it is reaching its connection limit at busy times.

Why does the front page work but wp-admin shows a database error?#

The front page is being served from a cache. Logged-in pages are never cached, so they show the real state of the site.

Can a plugin cause this error?#

Not directly, since the connection is made before plugins load. A plugin can cause it indirectly by running queries heavy enough to exhaust connections or memory.

Should DB_HOST be localhost or 127.0.0.1?#

Use localhost unless your host says otherwise. Switch to 127.0.0.1 only if localhost gives a socket error while the database is running.

The short version: read the four values in wp-config.php, try them by hand, and let the error number tell you whether the details are wrong, the server is down, or the server is full. Then fix that one thing.