WordPress Error Establishing a Database Connection: Fixes

Why WordPress shows a database connection error

Few things make a site owner sit up faster than seeing “Error establishing a database connection” at midnight. Visitors cannot load the site, /wp-admin/ is unavailable, and the message rarely identifies the failed layer. The web server may be healthy. MariaDB or MySQL may be stopped, the credentials may be wrong, the disk may be full, a table may be damaged, or the account may have reached a resource limit.

In support tickets, I often see the same first reaction: someone starts changing random lines in wp-config.php. That sometimes reaches the cause. It can also turn one problem into two. I begin by finding out whether the whole site is down or only one page, plugin, or administrative function is affected. Then I compare the web server, PHP, and database logs for the same time window.

Let me put it this way: one WordPress message can represent several unrelated failures. I work from low-risk observations toward changes that affect the site. Before repairing tables or editing configuration files, I make sure there is a usable backup.

Start with the first few minutes

First, establish the scope. Open the site in a private window, try another network, and check /wp-admin/. If only a custom page used by one plugin fails, you may be looking at a slow or broken query rather than a database connection failure.

If you have SSH access, I start with these checks:

df -h
free -m
systemctl status mariadb --no-pager
systemctl status mysql --no-pager

df -h shows filesystem usage, while free -m gives a quick view of memory. The last two commands check the service names commonly used on Linux systems. Depending on the distribution, the database service may be called mysql or mariadb. Do not restart both blindly. Read first.

I once handled a “site is down” ticket where access-log rotation had been forgotten. The root filesystem was at 100 percent, and the database failure we suspected was really a storage problem. Since then, disk usage has been one of my first checks, before I touch credentials or tables.

Use the same caution with commands copied from the internet. I do not begin diagnosis with a curl | sudo bash installer, and neither should you. Understand a command before giving it root access.

1. Verify wp-config.php without exposing secrets

WordPress normally reads its database settings from wp-config.php in the document root. I check these values:

• DB_NAME: the database name
• DB_USER: the database username
• DB_PASSWORD: the user’s password
• DB_HOST: the database hostname, address, or socket
• $table_prefix: the table prefix used by WordPress

A common post-migration mistake is importing the database while leaving DB_NAME or DB_USER set to the old account. Generating a new database password in a hosting panel and forgetting to update wp-config.php produces the same symptom.

Never paste the password into a support ticket, screenshot, or shared chat. To inspect the non-secret settings on the server, I use:

cd /home/username/public_html
grep -E "DB_NAME|DB_USER|DB_HOST|table_prefix" wp-config.php

This prints the basic settings without displaying the password. Compare the database name with the value in your hosting panel. cPanel and CyberPanel may add the account username to database and user names, so the correct value could be username_site_wp, not simply site_wp.

Test the credentials directly with the MySQL client instead of testing only through WordPress:

mysql -h 127.0.0.1 -u database_user -p database_name

Enter the password when prompted. A message such as Welcome to the MariaDB monitor shows that the credentials and network path work for that test. Access denied points to the username, password, or grants. Do not put the password directly in the command; it can remain in shell history.

2. Find out whether MariaDB is running

Correct credentials cannot help if the database service has stopped. Memory exhaustion, maintenance, and storage errors can all cause that. I check the service and its recent logs together:

sudo systemctl status mariadb --no-pager
sudo journalctl -u mariadb -n 80 --no-pager

Look for messages such as InnoDB: Unable to lock, Too many connections, Out of memory, and disk-write errors. systemctl status tells you whether the service is running; journalctl often explains why it stopped.

A full filesystem can prevent MariaDB from creating temporary files or binary logs. Use df -h to identify the full mount point, then inspect large directories with ncdu. Fix log rotation or the underlying storage problem. Do not delete random files, especially anything under /var/lib/mysql. That can turn a recoverable outage into data loss.

If the service is stopped and the logs do not show a configuration error, a restart may be appropriate:

sudo systemctl restart mariadb
sudo systemctl status mariadb --no-pager

A restart can restore access briefly, but the error will return if memory, disk, or connection pressure remains. On shared hosting, you will not have permission to restart MariaDB. Ask the provider to check the service state, disk usage, and database logs for the affected period.

3. Check DB_HOST and the connection socket

On many Linux servers, DB_HOST set to localhost makes the client use a Unix socket instead of TCP. The connection fails if MariaDB uses a different socket path or if the provider keeps the database on another server.

For a local database, I may test the loopback address:

define( 'DB_HOST', '127.0.0.1' );

localhost and 127.0.0.1 are not always equivalent. The first can direct the client to a Unix socket; the second requests a TCP connection. Back up the file first, and check the PHP syntax after editing it.

If the database is remote, use the hostname supplied by the provider. The remote firewall must allow the source IP, MariaDB must listen on an appropriate address, and the database user must have a grant for the correct host. user@localhost and [email protected].% are different grants.

For a non-standard port, WordPress accepts this format:

define( 'DB_HOST', 'db.internal.example:3307' );

After changing the setting, verify the destination and port. Two services can belong to the same project without running on the same machine. Confirm the hostname and port with the hosting provider.

4. Check the tables before attempting repairs

If the service is running and the credentials work but only some pages fail, a damaged table is one possibility. Power loss, a full disk, faulty storage, or an interrupted write can cause it.

Start with a database export. With SSH access and WP-CLI installed, I would run:

cd /home/username/public_html
wp db export /home/username/backup-$(date +%F-%H%M).sql

This writes the WordPress database to a timestamped SQL file. Confirm that the file exists, has a sensible size, and is copied to separate storage. One copy on the same disk is not protection against disk failure.

Then check the tables:

wp db check

If the command reports no errors, corruption becomes less likely. If it identifies damaged tables, ask your hosting provider or database administrator for the appropriate recovery procedure. InnoDB recovery is not the same as running the simple REPAIR TABLE command often associated with MyISAM.

WordPress also has a built-in repair screen. Add this temporarily to wp-config.php:

define( 'WP_ALLOW_REPAIR', true );

Then open https://example.com/wp-admin/maint/repair.php. Remove the line immediately afterward. The page does not require a login, so leaving it enabled creates an avoidable security risk. Start with the check-only option, and do not run repairs without a valid backup and a clear understanding of the damage.

If a WordPress update was interrupted, a .maintenance file may remain in the document root. That normally leaves a maintenance screen rather than producing a database connection error. If the message is Error establishing…, deleting .maintenance will not fix it.

5. Separate plugin failures from connection failures

A database can accept connections while a plugin opens too many connections, runs expensive queries, or causes PHP workers to time out. To a visitor, that may still resemble the familiar WordPress error screen.

If the administration area is unavailable, temporarily rename the plugin directory:

cd /home/username/public_html/wp-content
mv plugins plugins.off

If the site recovers, rename the directory back and activate the plugins one at a time. This does not delete plugin files; it only prevents WordPress from finding the directory for the moment.

WP-CLI gives me a more deliberate option:

wp plugin deactivate --all
wp plugin list --status=active

The first command disables active plugins, while the second shows the current state. On a production site, disabling everything removes important functionality temporarily. On a WooCommerce store, test the cart, checkout, payments, and order administration separately.

Check PHP and WordPress logs too. Leaving WP_DEBUG enabled in production can expose sensitive information to visitors. For temporary diagnosis, log errors without displaying them:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Inspect wp-content/debug.log, then disable debugging when finished. A repeated reference to one plugin file does not prove that MariaDB is healthy; the plugin may be exhausting connection slots or query resources.

Use the symptom to choose the first check

This table does not diagnose the fault. It helps me choose the first useful check. With intermittent failures, one successful connection test can be misleading. If Too many connections appears during busy periods, find the query or plugin consuming connections before increasing the limit.

Give support evidence, not just the error message

“My site is down” gives both sides very little to work with. Include when the error began, the affected domain, whether the outage is continuous or intermittent, the last change you made, and the exact message shown.

• Do not send wp-config.php; never share passwords or security keys.
• Write the time zone clearly, such as İstanbul time if that is where you are working.
• Mention the last plugin, theme, PHP, or server change.
• Attach the error screen and relevant log lines after masking sensitive data.
• If the site uses WooCommerce, say separately whether checkout, orders, and the administration area are affected.

Your hosting provider can inspect service logs, disk quotas, MySQL processes, and account limits. Clear symptoms replace the vague argument about whether it is “the server or the site” with evidence.

Reduce the chance of another outage

Before a WordPress update, I now run wp db export almost automatically. In my Proxmox lab at home, an update is allowed to fail on a test VM before it gets anywhere near a customer server. I also test restores. Once a month, I restore a random SQL backup and several WordPress files because a backup that cannot be restored is only a comforting filename.

Monitor disk usage, the MariaDB service, and your certificate-renewal cron job. My Raspberry Pi runs Uptime Kuma for exactly this reason: an unmonitored cron job can quietly stop working. On shared hosting, check panel alerts and resource-usage graphs regularly.

Keep WordPress core, themes, and plugins updated, but do not update blindly without a backup and a way to verify the result. Do not use admin as the administrator username or choose a predictable password. For the security checks I use around hosting accounts, see Web Hosting Security Checklist for Small Businesses.

After a database error, changing permissions to chmod 777 is not a fix. It changes the name of the problem, not the problem itself. Record the current ownership and permissions, then correct them so the web-server user can access only what it needs.

For a domain or server move, include DNS in the change plan. DNS Record Types Explained: Practical Guide to A, AAAA, MX, CNAME, TXT, SRV and CAA covers A records, TTL, and verification steps. Your database may be healthy while visitors are still reaching the old server, so a correct fix may not appear everywhere immediately.

Frequently asked questions

Can hosting cause a WordPress database connection error?

Yes. A stopped MariaDB service, exhausted disk space, account resource limits, or network access problems can all cause it. If other sites on the same server are affected, service and resource checks on the hosting side should come first.

Which lines in wp-config.php should I check?

Check DB_NAME, DB_USER, DB_PASSWORD, and DB_HOST. Also confirm that the database user can access that database. Seeing the expected text in the file is not enough; the credentials must work from the relevant host.

Is repair.php safe to use?

Take a working database backup first, and remove the WP_ALLOW_REPAIR line immediately afterward. The page is accessible without authentication, so leaving it enabled is a security risk. For InnoDB problems, choose the recovery method carefully instead of assuming that a simple repair command applies.

What should I check when the error is intermittent?

Search MariaDB logs for connection-limit, memory, and timeout messages. PHP-FPM processes, expensive plugin queries, sudden traffic, and storage latency can all cause intermittent failures. Changing only DB_HOST will not solve every case.

When I see this error, I start with the layers rather than the screen: disk, service, credentials, connection address, and queries. I save the output after each check. That small habit turns a midnight panic into an incident I can actually follow.