message Error establishing a database connection means WordPress could not establish a usable connection to MySQL or MariaDB. The cause can be wrong username or password, database service stopped, connections full, DNS or network error, limited table corruption or resource pressure. The first reaction should not be to repair or restore the database; First, it should be known that the connection is not established at all or the queries fail after the connection.
Quick answer: Record the time when the error started, take a backup of the current state, the values DB_NAME, DB_USER and DB_HOST without Compare password disclosure with actual configuration, see database service health and error log, and test connection from the same application host. Blind password change, repair and restart can destroy evidence or access to other services.
Error pattern is an important clue
| Pattern | Possible causes |
|---|---|
| After password transfer or change | wp-config, host, privilege or DNS |
| Occasionally at high traffic | Saturated connections, slow query, CPU or I/O |
| All connected services are down | Database, disk, network or crash service |
| Only one site on shared server | credential, database name or permission of the same user |
| wp-admin gives repair message | possibility of incompatibility or table corruption; Need more evidence |
Check wp-config.PHP settings closely
The four main values in wp-config.php are DB_NAME, DB_USER, DB_PASSWORD and DB_HOST. Do not publish the password in ticket, screenshot or command history. In shared hosting, the account prefix may be a part of the database and user name. In Docker, localhost is usually the WordPress container itself, not the database container; The service name or endpoint defined in the same network must be used.
The non-default port or socket must be specified according to the environment documentation in DB_HOST. Do not blindly copy the template of an example; How host is interpreted depends on the driver and PHP configuration.
Is MySQL really serving?
On systemd servers, read the status and recent events. The unit name may be mysql or mariadb:
systemctl status mysql
journalctl -u mysql --since "15 minutes ago"These commands do not change state. If the service is stopped, find the cause in the log before restarting: disk full, OOM, InnoDB error, and config errors have different paths. restart may bring the site back up temporarily but it hides the root cause.
Test the connection from where WordPress is running
Testing from your laptop does not confirm the production network path. The connection must be checked from the same VM or application container. To avoid logging the password in history, use the interactive client prompt:
mysql -h DATABASE_HOST -u DATABASE_USER -p DATABASE_NAMEError Access denied is not the same as Connection refused. The first is usually related to credential or privilege; the second to listener, host, port, firewall or service. Timeout mostly refers to network path or overload. Keep the full text of the error, but remove the secret.
Don't forget DNS, socket and container network
If DB_HOST is a hostname, check its resolution in the same PHP environment. The container may have different DNS and hosts file than the host. In Docker Compose, the service name can only be resolved on the shared network, and it is not necessary to publish the database port for internal communication. The Unix socket connection also depends on the existence of the same file inside the PHP execution environment; The host socket is not automatically visible inside the container.
If the database is remote, check the route, security group and origin restriction. Opening port 3306 is not an acceptable solution for all internet. Access should be established only from necessary sources and preferably on a private network or secure tunnel.
Connection resources and capacity
If the error is intermittent, compare the number of active connections, slow queries, CPU, RAM, I/O and OOM events in the same interval. Increasing max_connections without accounting for memory can make the crash more severe. A faulty connection pool or plugin may also not release the connection. First, the consumer and the duration of the query should be specified.
When will repair be proposed?
repair is not applicable for wrong credential or disabled service. Only when the log and the database tools show the table failure, proceed with a valid backup and recognize the engine. fixed WP_ALLOW_REPAIR creates a page without the usual admin authentication; If it is used temporarily, it should be deleted immediately. For InnoDB, the recovery method should be selected based on the actual MySQL message and the backup status, and it is not recommended to run the changing commands without a recovery version.
What are the most common errors after site transfer?
- The database or user name is different at the destination from the source.
- The user is created but the database privilege is not granted correctly.
- The old hostname, private IP, or Docker service name has changed.
- Firewall only allows the previous subnet.
- The internal DNS or TLS database is not set to the destination.
Risk errors
- Place real password in command, chat or public log.
- Remove and recreate database user without checking other users.
- Immediately restore old backup in store and delete new orders.
- Grant more access than needed, such as global privilege for a temporary solution.
- Delete InnoDB files or manipulate the data directory.
When is multi-layer checking necessary?
If the connection is intermittent, MySQL crashes, replication or Docker is in the way, or the data store is live, testing on production can increase the definitive range. In WordPress technical troubleshooting service you can check wp-config, network, privilege, MySQL log and system resources side by side without guessing. If the general server response is 500, WordPress 500 Error Guidecovers the web server and PHP path.
Frequently Asked Questions
Does this error mean the database has been deleted?
No. The message only indicates a usable connection failure. The existence and health of the data should be checked separately with the database tool.
Why is the error resolved automatically?
The connection may be free, the service restarted or the pressure is low. This pattern requires checking the timeline and does not mean to fix the cause.
Is localhost always correct?
No. It is common in single server installation, but in Docker, the remote database or custom socket must be the real endpoint of the environment.
Can the database password be changed?
Yes, but all users must be synchronized and the secret must be updated securely. A hasty change may disrupt more services.