WordPress database connection problems are common when installing, upgrading or even migrating a WordPress blog or website. There are several other scenarios were MySQL database connections can fail, and they can all be solved in the same easy way. In this article we will explain in step by step format how to easily troubleshoot and solve WordPress database connection problems.
How and where WordPress stores information
WordPress is a PHP web application that stores all the information in files and in a MySQL database. Images and other media related content are saved as files in /wp-content/uploads/ directory, while all other content and information, such as blog posts, links, usernames and passwords are stored in the MySQL database.
When installing WordPress you have to specify the database name, database username and password, and the hostname of the MySQL database server in the wp-config.php file, as per the example below.
/** 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');
When you encounter the “Error establishing database connection” error message, most of the times the issue is related to one or more of to the above mentioned entries, such as a wrong host, wrong username or password or wrong database name. It could also be a user rights issue, i.e. the configured user does not have access to read from or write to the WordPress MySQL database.
WP White Security.com security tip: When creating a MySQL database for your WordPress, create a dedicated user with read and write permissions to the WordPress MySQL database only. Never use the MySQL root account for such operations.
Troubleshooting WordPress Database Connection
If the error ‘Error establishing database connection’ is showing up instead of your WordPress blog or website, first check that the host, i.e. the MySQL Server address is correct. Once you confirm that the host is correct, confirm that the MySQL username and password specified in the wp-config.php file are correct and that the user has access to read from and write to the WordPress MySQL database. Below are the two test procedures explained in detail.
Testing tool for WordPress MySQL database
- Download the WordPress MySQL database connection test tool from here.
- Replace the entries mentioned below from the code with the same entries you’ve entered in the WordPress configuration file wp-config.php:
- #HOST: IP address or hostname of the MySQL database server
- #DB_USER: the username used to access the WodPress MySQL database
- #DB_PASSWORD: the password of the MySQL user
- #DATABASE: the name of he database
Once you change the details, save the changes and upload the file to your WordPress using an FTP client. Navigate to the file URL uploaded on your website to start the test. E.g. if you uploaded the file dbtest.php to the root of your website, the URL is http://www.yourwebsite.com/dbtest.php.
Once you run the test, if everything is configured correctly you should see the below success test messages:
- Successfully connected to MySQL database server.
- WordPress MySQL database selected.
This means that the host, the credentials to access the WordPress MySQL database and permissions are correct. If you get any other error message, refer to the below list of error messages for more information on how to solve the issue.
MySQL Host and database credentials error messages
The results in the first line are related to the MySQL Host and the database credentials. Below are the possible errors:
 A connection attempt failed because the connected party did not properly respond after a period of time
This means that the Host you specified is not correct, or the MySQL database server is down and unreachable. If you are not sure about which host you should use for the MySQL server, contact your hosting provider.
No such host is known
Same as above; MySQL Server is unreachable.
Access denied for user ‘db_user’@’localhost’ (using password: YES)
This means that the username or password you are using are incorrect. To solve this issue, login to your hosting provider control panel and make sure you copy the correct username. If you are not sure what the password is, from the hosting provider control panel or from the PhpMyAdmin web interface, change the password for the database user.
Note: Before troubleshooting WordPress MySQL database user rights, first you must be able to successfully connect to the MySQL Server. So before troubleshooting any errors in the second line, the first line should be should always be ‘1. Successfully connected to MySQL database server’.
WordPress MySQL database access
The result ofthe second line of the test is related to the MySQL database user access, i.e. it checks if the user can at least read from the WordPress MySQL database. If the second line is ‘2. WordPress MySQL database selected’, it means that you are using the correct database and the user has access to read from it. If you get any other error, refer to the below list for more information:
Unknown database ‘db_name’
This means that the database name you specified does not exist on the MySQL server. In this case the database name is wrong. Refer to the hosting provider cpanel to get the correct database name.
Access denied for user ‘localusr’@’localhost’ to database ‘localdotcom’
The above error means that the database exists but the user you specified in the WordPress configuration file wp-config.php does not have access to read from the MySQL database. In this case you have to give permissions to the user to be able to access the WordPress MySQL database. You can do so from the hosting provider control panel or from the pypMyAdmin web interface.