Of the most common errors you might encounter with WordPress, an error establishing a database connection is among the most frustrating.
When faced with such an issue, we understand that resolving this error message and restoring the site’s regular operation is a top priority, and we’d be happy to guide you through the process.
Why am I seeing Error Establishing a Database Connection?
An Error Establishing a Database Connection means that your site cannot retrieve the backend data from MySQL.
Such a situation results in the entire website being offline and unavailable, including the wp-admin backend-administration panel.
There are quite a few potential causes of the Error Establishing a Database Connection message.
However, before we discuss potential causes, it’s helpful to know a bit about the background of the WordPress platform to see what makes this error message may appear in the first place.
WordPress has two main components; one at the file system level and another at the database level. Each has different functions that combine to form the WordPress platform.
Files
WordPress stores all of the PHP code used by the WordPress core at the file system level, along with themes, plugins, uploaded media files, and a few configuration variables.
Viewing file system-level data is possible using a web browser to access cPanel or an FTP client, such as FileZilla.
Database
WordPress stores all customization data at the database level. That means the database contains all of the site’s posts, pages, comments, theme and plugin settings, and much more.
Viewing the raw MySQL data is only possible using PHPMyAdmin, downloading a SQL dump, or using the command-line MySQL client via SSH.
So, the Database Connection error indicates that something is interfering with the WordPress access to the database. Since WordPress can’t retrieve the necessary details from the MySQL backend, it cannot load the requested page in your browser.
Why do I see the Database Connection error only on some of the pages or wp-admin?
If you have a caching plugin configured, you may notice that some pages on the front end still load as expected. This often happens even with the Database Connection error.
With proper rewrite caching enabled, the front end of WordPress is pre-generated static files. So, you may notice the front end is still “working” even though the wp-admin backend is unavailable.
These pages still load because the caching plugin converts pages into pre-generated static files. When a visitor requests a previously cached page, the results are served from the static cache and not generated in real-time by the website.
Thus, they do not require a MySQL connection.
Caching also significantly improves your overall website’s performance and reduces resource consumption. This is because a significant portion of traffic is served directly from the cached files.
In other words, caching is doing exactly what it’s supposed to do.
Top Causes of the “Error Establishing a Database Connection”
- Incorrect MySQL Details
- WordPress uses the MySQL database, username, and password information from within the wp-config.php file in the local WordPress directory.
- The information in this file is case-sensitive and must match the MySQL database credentials provided by your hosting provider.
- The WordPress table prefix must match those in your MySQL database.
- The MySQL user must be assigned to the database and have the proper MySQL permissions.
- Corrupted MySQL Database
- If particular MySQL tables are corrupt, WordPress will show an error as it cannot load critical site information from MySQL.
- The most common cause of this issue is a failed or partial update of the WordPress core, theme, or plugin.
- The wp_options table is the one most commonly corrupted.
- The MySQL Host is Unavailable
- If a connection error is displayed but resolves itself without further action, it may be that the backend MySQL server was temporarily offline.
- The Site Has Reached the MySQL Connection Limit
- There’s a limit to the number of allowed MySQL connections both per-user and globally for the server.
- High Traffic Levels
- Large amounts of traffic, especially if the site is not well optimized, may overwhelm the resources available.
- If the site runs out of available resources, intermittent errors may result.
- Corrupted WordPress files
- Although the issue refers to the Database, WordPress may be corrupt at the file system level.
- WordPress corruption is most commonly the result of a failed update of the WordPress Core or an automatic update of a Theme and/or Plugin.
How To Fix “Error Establishing a Database Connection”
Before diving into step-by-step debugging, the first thing to do is reach out to the web hosting provider to confirm that this is not a server-side issue.
Reach Out to Your Web Hosting Provider
The provider’s support team will be able to advise you of any recent disruptions to your service.
Once you’re in contact with the provider’s support team, ask them to check that the MySQL service is functioning normally and if your account is seeing any spikes in resource usage or visitor traffic that may explain the issue.
Once you’re sure there’s nothing wrong with the hosting account, or the webserver, you can start the step-by-step debugging or ask your provider for further assistance.
Double-Check the MySQL Information
Since invalid MySQL details are one of the most common causes of this issue, double-checking the wp-config.php should be first on the list.
The local wp-config.php file contains all of the settings required by WordPress to access the MySQL database, including the MySQL database, username, password, table prefix, and various other options.
A mismatch between the credentials set in MySQL and those in the local wp-config.php will result in a connection error.
Open up the cPanel File Manager or your favorite FTP client and navigate to the WordPress directory. Then, open up the wp-config.php file in an editor.
Locate the values for DATABASE_NAME, DB_USER & DB_PASSWORD, as we need these to compare in cPanel.
Once you have the wp-config.php file open, and located the above values, navigate to the MySQL Databases page in your cPanel. On that page will be a list of Databases and Database Users.
Confirm that the database name and user from wp-config.php match those listed on the cPanel MySQL Databases page.
We cannot view the existing password, but we can reset the password to use the one from wp-config.php by clicking “Change Password” next to the Database User on the MySQL Databases page in cPanel.
Resetting the password ensures the password in wp-config.php matches the password in MySQL’s backend for that user.
Repair the MySQL Database
Now that we can be sure the MySQL information listed in wp-config.php is correct, we can attempt to repair the database itself.
The WordPress backend MySQL database contains many tables with site configuration data. Some of these tables, like wp_options, are critical to the site. The site will fail to load if these tables are broken or corrupt.
To check these tables, we can use the MySQL Repair tool in cPanel.
Access the MySQL Databases page.
Select the database listed in the wp-config.php for WordPress under the Repair Database drop-down box. This is located under the “Modify Databases” section.
Click the “Repair Database” button to start the process.
The repair process runs after each table is checked individually. Large databases may take a few minutes to finish the MySQL repair.
The repair won’t harm the “good” tables as the tool will only attempt to fix only the flagged tables.
Replace the WordPress Core files
The files necessary for WordPress to connect to the MySQL backend database may be missing or corrupted.
In most cases, the files get corrupted from a partial or incomplete update to the WordPress core files. The good news is that we can refresh the WordPress core files without losing your website data or customizations.
WP CLI
The easiest way to do this is using the WP CLI toolkit via SSH or the cPanel Terminal tool.
Navigate to the WordPress directory (i.e. public_html).
cd ~/public_html
Then, use the WP CLI tool to re-download the WordPress core files only, replacing the existing corrupted or missing files:
wp core download --force --skip-content
WordPress Archive
If you aren’t comfortable using the cPanel Terminal or SSH access, you can replace the WordPress core files by uploading a fresh copy of WordPress via FTP.
Visit the WordPress download page and obtain the latest version of the WordPress archive: https://wordpress.org/download/#download-install
Once you have downloaded the latest copy of WordPress locally, extract the WordPress files to your local PC and navigate to this folder in your file explorer.
Delete the newly extracted directory wp-content, as we do not want to overwrite our existing wp-content directory.
Open the FTP client and navigate to your WordPress directory (i.e public_html). Once in the WordPress directory on the web server, you can upload the files from your local PC’s newly extracted WordPress folder (the one without the wp-content folder).
Click Yes when asked to overwrite any existing files or folders.
The FTP upload may take some time as there’s a large number of small files that make up the WordPress core.
Restore a Backup
If all else has failed, you can restore a backup of the affected site as a full backup contains the site’s files and a copy of the MySQL database.
If you don’t have a copy backup of the website, you can try to reach out to your web hosting provider. Ask if they have a copy, as most providers take automatic backups of customer data.
Sometimes, It Takes a Bit of Troubleshooting
Unfortunately, as with many other issues on the Internet, fixing the Error Establishing Database Connection problem takes a bit of detective work. That’s because not all situations are the same.
It’s uncommon to have a one-size-fits-all answer. However, a lot of troubleshooting isn’t all that difficult to complete yourself.
Still, there’s nothing wrong with reaching out for assistance if you don’t know exactly what you’re doing. It’s easy to cause additional damage if you’re not sure.
