WordPress database connection problems are very common, especially when installing, upgrading and migrating a site. However, they can also occur on other occasions. If you have a WordPress site you’ve surely seen the error establishing database connection:
WordPress database connectivity problems can be solved very easily. This article explains how to use our database connection tool to troubleshoot and solve WordPress <> My SQL database connectivity problems.
Common Causes of WordPress Database Connection Problems
In short, the Error establishing a database connection problem occurs when WordPress cannot connect to the database on the MySQL database server. This is caused by any of the below:
- The database configuration details in WordPress are incorrect
- The MySQL database server is unavailable (it is down, very busy or unreachable)
- Incorrectly configured WordPress database privileges on the database server
Troubleshooting the WordPress Database Connection Error
If the error ‘Error establishing database connection’ is showing up instead of your WordPress blog or website, first check that the database configuration in WordPress is correct.
Where are the Database Connection Details Configured in WordPress?
WordPress is a PHP web application that stores data in a MySQL database. It uses the database connection details configured in the file wp-config.php to connect to the database, which can be found in the site’s root directory. Below is an abstract from the file where the database connection details are configured:
/** The name of the database for WordPress */ define('DB_NAME', 'database_name_here'); /** MySQL database username */ define('DB_USER', 'username_here'); /** MySQL database password */ define('DB_PASSWORD', 'password_here'); /** MySQL hostname */ define('DB_HOST', 'localhost');
Most of the times database connection issues happen because one of the above entries are not configured correctly. So check that all of the above are correct:
- database server’s name or IP address
- database name
- username and password of database user.
WP White Security.com security tip: Create a dedicated user with read and write permissions for the WordPress MySQL database only. Never use the MySQL root account for such operations.
If the database connection details in the wp-config.php file are correct but the connection still fails, then you either have incorrect details, or there are problems with the database server or privileges. In such case use our simple tool to test the database connection and find out exactly what the issue is.
Testing tool for WordPress Database Connectivity Tests
Follow the below procedure to test the WordPress database connection and find out the cause of the problem:
- Download the WordPress MySQL database connection test tool.
- Replace the entries mentioned below from the code with the same entries you’ve entered in the wp-config.php WordPress configuration file:
- #HOST: IP address or hostname of the MySQL database server
- #DATABASE: the name of he database
- #DB_USER: the username used to access the WodPress MySQL database
- #DB_PASSWORD: the password of the MySQL user
Once you update the database connection details save the changes and upload the file to your WordPress. Navigate to the file URL uploaded on your website to start the test. E.g. if you uploaded the file wpdbtest.php to the root directory of your website, the URL is http://www.yourwebsite.com/wpdbtest.php. If the configuration is correct, you should see the below success message:
It there are database connectivity problem the tool will display an error message and error code highlighting the problem, as shown in the below screenshot. Refer to the below list of error codes and explanation to find out what is wrong with the connection and solve the issue.
MySQL & WordPress Database Connection Errors
The below is a list of the most common MySQL server database connection error codes and descriptions.
|Error Code||Cause & Resolution|
|1040||Too many connections. Try to reduce the number of processes / applications using the database server or distribute the connections to other servers.|
|1041||Out of memory. You can restart the server to fix this issue though it might happen again. If so, increase the memory allocated to your database server.|
|1043||Bad handshake. This means the database connector you are using is using a different protocal than the one the server uses, so they cannot communicate. This is a server configuration issue. Speak to your web host.|
|1044||Access denied for user to database. This means that the database user credentials are correct. However the user does not have acess to the database.|
|1045||Access denied for user using password. This means that the credentials are incorrect so you cannot connect to the MySQL server. Check that the username and password are correct.|
|1049||Unknown database. The database you specified in the configuration file does not exist on the server.|
|2002||Connection timed out. This means that the database server is unreachable. So it is either down or you are using the wrong IP address. Check with your web host to confirm the IP address.|
Summing It Up
It is very easy to fix the Error establishing database connection issue in WordPress, especially with our database connectivity test tool. It pin points the problem so you do not have to troubleshoot and do any guesswork. Should the issue be database privileges or server configuration contact your web host’s support if you are not familiar with MySQL.