Encountering a database connection error can be frustrating, because it prevents you from accessing your site–including the WordPress Admin Dashboard! In this article we explain what causes the “Error establishing a database connection” error, and how to resolve this error if you encounter it.
About database connection errors
If your website is having an issue locating the database for your website, you will likely encounter the following error:
Error establishing a database connection
This error happens when your configuration files are referencing the wrong database, or your website isn’t able to connect to the right database. While this error is not specific to WordPress and could happen for any website with a database, on WordPress sites the most common cause is a misconfiguration of your wp-config.php file.
Resolving database connection errors
If a database connection error occurs, it can be frustrating because neither your website or WordPress Admin Dashboard are accessible. However, you can resolve this error a couple ways as long as you have access to your WP Engine User Portal.
Restore your site
Option one, if it is viable for your website, is to restore to the last normal backup point. WP Engine automatically backs up your website each night, and you are also able to make a backup at any time on command. Any of these backups can be restored to restore the wp-config.php file to a good state.
After logging in to your User Portal, navigate to the Overview page for your website environment. Select Backup points from the left-hand navigation, then select the backup you’d like to restore from the list.
Select Restore, confirm whether or not to include the database in the restore, and which email address should receive notifications about the restore. Once you receive an email indicating the restore completed, your website should be back to normal.
If restoring is not a viable option or it does not fix your issue, you can choose to edit your wp-config.php file via SFTP instead. Before getting started, make sure you have downloaded an SFTP client and setup an SFTP user–instructions are available in our SFTP guide.
Connect to your website using your SFTP client and credentials. Your wp-config.php file will be in the root directory of your website–select the file to view and edit it.
In the wp-config.php file, pay special attention to the database settings near the top. On WP Engine, your database name will always be wp_[environment-name] and your database username will always be your environment name.
In the example above, the DB_NAME is ‘wp_notarealdatabase’ and the DB_USER is ‘notarealuser,’ which is incorrect. Updating these settings to the correct database name and username will resolve the issue.
Once the correct settings are in place, save the file–if your SFTP client prompts you to confirm the change, ensure you confirm “yes” to save the file to your website’s server. After saving the file, refresh your browser–your website should now be back online!
If you are encountering a database connection error and have been unable to resolve it, feel free to contact WP Engine Support for more help. Our Support teams are available via Live Chat 24/7 in your User Portal to help get your website back online. When contacting Support please be sure to include your environment name, any contextual events that lead up to the error, and any steps you have already taken to try to fix the issue.