The “Error establishing a database connection” is one of the most common issues that WordPress website owners can encounter. Aside from being one of the most frequently seen WordPress error messages, it has also earned its place among the most serious of them, leaving the website completely inaccessible should something interrupt WordPress’ ability to communicate with its database.
But what does it mean when it says error establishing a database connection? Your WordPress website is a dynamic, database-driven application which means that if the requested data can not be retrieved from the database, WordPress will show an error message until the underlying issue is resolved and a successful connection can be established.
Follow our comprehensive guide to WordPress database connection errors to learn how to fix the “Error Establishing a database connection” message on your website in a step-by-step manner.
The WordPress Database And Its Role In Content Rendering
Content rendering can be described as the process of delivering the requested content to your website visitors. WordPress abstracts away the complexity of the process, which means that you as a website owner have little to no need to interfere in the way it works to make your WordPress website work correctly.
Your WordPress database stores the vast majority of the content you create, including posts, pages and some other data that allows WordPress to generate dynamic web pages. All this information needs to be loaded from the database and further processed by WordPress to create an HTML file that will then be sent to the visitor.
PHP uses a special extension called a database driver to establish connection to the WordPress database using the credentials provided in the WordPress configuration file. When the credentials provided are incorrect, a database driver is missing, or the database server is not responding — all these issues can interrupt content rendering, resulting in the “Error establishing a Database Connection” message shown on your WordPress website.
What is The Error Establishing a Database Connection in WordPress?
The “Error establishing a database connection” is an error message that WordPress generates to let you know that it failed to establish a successful connection to the WordPress database during content rendering.
As WordPress heavily relies on the ability to perform database queries to retrieve the requested data to generate any web page, the “Error Establishing a database connection” is an error affecting the whole website, including the admin area. It means that when WordPress is experiencing database connection issues, you have a very limited number of tools at your disposal to bring your website back online.
5 Main Reasons Behind The Error Establishing a Database Connection
The “Error Establishing a Database Connection” message on your website indicates that WordPress has experienced critical issues in an attempt to connect to its database. As we discussed, issues can be encountered at all stages — from sending an initial request from PHP to actually communicating with the database server and providing authentication information to gain access to the database.
This is why it is extremely important that you identify the underlying issue as the key part of troubleshooting WordPress database connection issues. Without knowing what caused the issue, simply applying known fixes can bring you further away from solving it and restoring the functionality of your WordPress website.
The five main reasons behind the “Error Establishing a Database Connection” in WordPress include:
- The WordPress database credentials provided in wp-config.php are incorrect.
- The WordPress database user does not have sufficient privileges
- Your WordPress database is corrupted.
- Your database server is experiencing issues.
- Your WordPress website is hacked.
Reason 1: Your WordPress Database Credentials In wp-config.php Are Incorrect
WordPress uses the database credentials specified in the wp-config.php file to establish a connection to its database. The information required to make a database connection is provided using the four main constants:
- DB_NAME. Represents the name of your WordPress database.
- DB_USER. Defines the MySQL/MariaDB user that has been granted access to the WordPress database.
- DB_PASSWORD. Stores the value of the WordPress database user’s password.
- DB_HOST. Identifies the database server WordPress will send connection requests to.
As the name suggests, constants are used to store information that can not be changed during the script execution. If any of the information above stored in the wp-config.php file is incorrect, WordPress will not be able to establish a database connection successfully. It will inevitably lead to the “Error establishing a Database Connection” message showing on your WordPress website.
As WordPress has no other way of obtaining database credentials other than simply reading the values you put in the main WordPress configuration file, it is extremely important that you make sure all information is updated there once you make any changes to it. It can include website migration to a new server, cloning, or just changing the WordPress database user’s password in case it has been compromised.
Reason 2: Your WordPress Database User Does Not Have Sufficient Privileges
When WordPress makes a connection to its database, it authenticates as the database user specified in the wp-config.php file. However, even if the password you provided is correct, and the database server accepts the connection, without sufficient privileges, it won’t allow the user to access any information.
Each MySQL/MariaDB database user has a list of databases it has been granted access to. Moreover, database privileges define what operations the user can perform on the database data.
WordPress requires the database user to be able to perform all kinds of database operations, including viewing, adding, and removing data from the tables. If the user does not have sufficient privileges, you will see the “Error establishing a database connection” message on your website.
Reason 3: Your WordPress Database is Corrupted
Database corruption, which represents a situation when certain data in your WordPress database has been damaged or removed, is another reason behind the error establishing a database connection on your website.
Your WordPress database data is stored in the system as files on the disk that get loaded when certain operations need to be performed. When some of the files are damaged, your database server fails to load the database, resulting in it being completely inaccessible to WordPress. The same happens when one of the vital WordPress database tables is removed, leaving WordPress unable to load your website.
It can happen for a number of reasons, ranging from the database server issues caused by hardware or software failures to human errors and even hacks – all resulting in data loss or incorrect representation of the vital information. WordPress will not be able to communicate with its database until data integrity is restored.
Reason 4: Your Database Server Is Experiencing Issues
Your database server is constantly waiting for new connections and working to serve all requests by executing queries and returning the requested data. Any interruption to the correct work of your database server can result in very serious consequences.
If your MySQL/MariaDB database server does not accept any connection requests, which can happen when it is offline entirely, overloaded, or experiencing other issues, WordPress won’t be able to establish a connection to its database, and you will see the “Error Establishing a database connection” message on your website. Database server issues are not easy to troubleshoot, so it can be considered the most serious reason behind WordPress database connection issues.
Database server issues can include serious conditions like tablespace corruption or no disk space left on the server, each causing MySQL/MariaDB to fail and not be able to start without the intervention of a system administrator. At the same time, your database server can simply get overloaded with requests as a result of a traffic spike or a DDOS attack.
Reason 5: Your WordPress Website Is Hacked
Hackers are constantly finding new ways to gain control of your WordPress website, and there is an endless number of ways to break it to the point where it becomes completely inaccessible. While we are listing hacks as a separate reason for seeing the error establishing a database connection on your WordPress website, when a WordPress website was hacked, multiple of the issues we have previously mentioned can be seen at once.
There is no way of knowing how the hacker will modify the functionality of your WordPress website to exploit it. Your WordPress files and database information can be removed or altered to the point where WordPress will no longer be able to function correctly, breaking the connection between all components of your website.
Incorrect database credentials or user privileges, WordPress database corruption, database server issues, and hacks represent the five main reasons behind seeing the “Error Establishing a database connection” message on your WordPress website. However, there are a few other issues that can potentially cause database connection issues in WordPress. These include failed WordPress updates or having a database driver missing from the PHP version used.
If a database driver is missing from the PHP version in use, PHP will not be able to connect to the WordPress database. A similar situation occurs if your WordPress core files have become corrupt. Most likely, you will see the “Your PHP installation appears to be missing the MySQL extension which is required by WordPress” message, “500 internal Server Error”, or “There has been a critical error on your website”, but seeing “Error Establishing a Database Connection” is not uncommon too.
How to Fix the “Error Establishing a Database Connection” Message in 3 Steps
Troubleshooting WordPress database connection errors includes understanding what caused it and taking the necessary steps to restore a normal connection between WordPress and its database. You can fix the WordPress error establishing a database connection in three steps:
- Make a connection to the WordPress database manually.
- Identify the underlying issue.
- Restore the database connection.
Step 1. Make a Connection to The WordPress Database Manually
The first and the most important step to troubleshooting the WordPress error establishing a database connection is testing whether you can connect to your WordPress database using the credentials specified in the wp-config.php file. You can use either MySQL commands or the WordPress Command Line Interface.
The wp db query command provided by WP CLI allows you to check if your database server accepts connection requests, the password in wp-config.php is correct, and the database user has sufficient privileges. You do not need to give the command any arguments, WP CLI will automatically read the values of the WordPress constants specified in the main WordPress configuration file.
The command can produce one of the three possible outputs — two indicating that the connection has failed, and one indicating that it has been successfully established. The output you receive will help you narrow down the list of possible reasons behind the WordPress error establishing a database connection.
Step 2. Identify The Underlying Issue
Depending on the output you received, you will be able to identify the issue behind the “Error establishing a database connection” message in WordPress. Let’s take a look at both cases — when a connection has been established and when WP CLI failed to connect.
The Connection Failed
If the database connection you attempt fails, you will see one of the outputs below. Both outputs indicate that a connection has not been established, but the error message displayed will let you know what issues have occurred.
The first error message shows that the database server accepted the connection request, but access to the database was denied. It means that you either failed to authenticate or the database user does not have sufficient permissions to access the WordPress database and run queries.
The second output indicates that the database server did not accept the connection request, which means that MySQL/MariaDB is either offline or overloaded with requests to the point where no new connections can be accepted. There is a limit on the number of simultaneous requests allowed, and if the limit has been reached, every new request will simply be rejected, leaving your WordPress website showing the “Error establishing a database connection” message.
A Database Connection Was Established
If the connection you attempt is established successfully, you will see an output similar to the one below, which means that WP CLI is able to connect to the WordPress database using the credentials specified in the wp-config.php file, and the database user has the required privileges. As the connection has been established, you will be able to run queries or view table data from the MySQL command line client.
The fact that a successful connection has been established means that your database server is up and running and not overloaded with requests to the point where no new connections are allowed. But even if you could connect to your WordPress database from the command line, it does not guarantee that the WordPress error establishing a database connection will be gone.
Step 3. Restore The Database Connection
Depending on the output you received trying to connect to your WordPress database from the command line, you will need to take different steps to restore WordPress’ ability to connect and fix the “Error establishing a database connection” message on your website.
A Database Connection Was Established
If you were able to establish a connection, but your WordPress website is still inaccessible, it might indicate that some vital data is missing from the database to the point where WordPress can not load the required information. The good news is that you can probably repair the database without having to restore it from a backup.
You can repair your WordPress database by using WP CLI, phpMyAdmin, or the graphical user interface WordPress provides. Running the wp db check and wp db repair commands will help you check your WordPress database for any issues and repair it.
WordPress has a built-in feature that allows you to repair your database even if your website is showing the “Error establishing a database connection” message. Add the line below to your wp-config.php file to be able to get access to the WordPress database repair interface.
Open your-wordpress-site.com/wp-admin/maint/repair.php, where your-wordpress-site.com is the domain name of your WordPress website, and choose Repair Database or Repair and Optimize Database.
After your WordPress database has been repaired, you should no longer be getting the “Error establishing a database connection” message on your website. Do not forget to remove the constant from your wp-config.php file afterward.
The Connection Failed
Depending on the error message that appeared after you tried to establish a connection to your WordPress database from the command line, you may realize that the credentials in the wp-config.php file are incorrect, the database user does not have sufficient privileges, or that the database server does not accept any connections.
Open your wp-config.pp file and examine your database connection settings. You may realize that some information is missing, or the user password was not updated thereafter it was changed.
Open your web hosting admin panel and navigate to the database management interface. If you are using cPanel, you will need to open the MySQL Database interface from your WordPress site’s cPanel account. Make sure that the database user specified in wp-config.php is correctly associated with the WordPress database and has been granted all privileges. Update its password and put the correct information in the WordPress configuration file.
Reload your WordPress website to see if the “Error establishing a database connection” message is gone.
If you continue to see database connection errors, repair the database following the procedure outlined in the previous section.
If you could not connect to the database server at all and suspect that it is offline or overloaded with connections, it’s best to contact your web hosting provider to request further assistance. Server-side issues can be difficult to resolve, and an incorrect approach to troubleshooting can lead to serious consequences, including data loss.
If None Of The Solutions Above Helped
If none of the solutions above have worked for you, and WordPress still fails to establish a connection to its database, it might indicate more serious issues that will need to be further investigated. Your web hosting support team will be able to find out what exactly caused the “Error establishing a database connection” message on your website and provide you with the best solution.
You may have to restore your WordPress database or the whole website from a backup or remove malicious injections and scripts that have been put there to break it.
How to Prevent Future Database Connection Errors: 3 Tips
Taking a mindful approach to website administration is the best way to keep it safe from various threats and avoid errors. As WordPress relies on the ability to connect to its database to retrieve the required data, making sure a successful database can be established at all times is key to preventing future errors.
1. Perform Regular Reviews Of Your Website And Its Configuration
Performing regular reviews of your WordPress website’s content and making sure all changes in your web hosting are reflected in the WordPress configuration file is essential. It is especially important to keep the database authentication information that WordPress relies on to establish a connection to its database up to date.
Do not forget to update your WordPress database credentials in wp-config.php each time you make any changes to the database user’s password or your database server that can potentially affect the way WordPress communicates with it. It is especially important to update all WordPress configurations when you move your WordPress website to another server, clone it to create a staging environment, or use a new domain name.
2. Invest in Quality Hosting
Whether your website stays online 24/7 and how much time you will need to spend troubleshooting errors appearing on it depends on how well web hosting services are optimized for WordPress to accommodate traffic. Choose scalable hosting solutions that can guarantee that your website will not be overloaded with requests and become inaccessible even when you host a huge promotion.
Your web hosting support team should proactively monitor the production environment, run updates, and address any server-side issues. This includes a rapid response to DDOS attacks that can leave your server unable to handle any requests and bring your website down.
3. Secure your WordPress Website
Security is one of the most important aspects of running a business online. With the rise of cyber security attacks, no website owner is protected from the various threats that the global network presents. If your WordPress website gets hacked, most of the time, the attackers gain access to your database, which allows them to add new admin users and wreak havoc on your business. Malicious code injected can lead to very destructive consequences, leaving your website fully inaccessible or not functioning correctly.
We recommend that you install a WordPress security plugin like iThemes Security Pro to secure your WordPress site. iThemes Security Pro offers 24/7 website security monitoring, brute force attack protection, a site scanner for vulnerable plugins, themes, and WordPress core versions, and enhancements for user security like two-factor authentication.
4. Perform Regular Updates
The majority of the time, hackers gain access to your website by exploiting a known vulnerability; that is why the importance of performing regular updates is hard to overestimate. Make sure your WordPress installation, all plugins, and extensions are updated to the latest version.
The best approach to software updates is having the process fully automated. The Version Management feature provided by iThemes Security Pro allows you to configure automatic updates for WordPress core, plugins, and themes, and perform scans that will help identify all outdated software.
Are you managing multiple WordPress sites? A tool like iThemes Sync gives you one central dashboard to manage updates for all your WordPress sites in one place.
5. Configure Automatic Backups to Run on a Schedule
Being able to restore your WordPress website in case an error occurs is one of the most important aspects of website administration. Backups help protect your website from data loss and other destructive consequences of security breaches and server-side issues. Make sure you have regular backups configured that save your data to a safe location.
Using a backup plugin for WordPress is a great way to ensure that you can restore your website at all times in just a few clicks. Over a million WordPress websites are protected by the BackupBuddy WordPress plugin from iThemes, which allows you to back up and restore every component of your WordPress website within minutes.
6. Keep Your Website Protected From Security Threats
Rapid response to security threats and taking a proactive approach to ensuring security is key if you would like to minimize the likelihood of your website experiencing errors and becoming inaccessible to its visitors.
Hacks can cause all components of your website to break, leaving you unable to restore the functionality and bring it back online. You need a security solution optimized for WordPress that will protect your website from known threats and keep hackers away.
The iThemes Security Pro is a plugin working as an application-level security solution that filters out malicious requests and blocks unauthorized access to the most vulnerable parts of your website. The iThemes Security Pro Site Scan feature allows you to run vulnerability scans that will alert you if you have a theme, plugin, or WordPress core version with a known vulnerability.
As with all database-driven applications, WordPress relies on the ability to establish a connection to its database and run queries to retrieve the requested content. The “Error establishing a database connection” message is generated by WordPress when it could not communicate with the database server successfully, which can happen for a number of reasons.
Knowing what WordPress needs to make a database connection and how to restore normal communication between your website and its database will help you address database connection errors and keep your website online for its visitors.
Get the bonus content: A Guide to WordPress Security
Kiki has a bachelor’s degree in information systems management and more than two years of experience in Linux and WordPress. She currently works as a security specialist for Liquid Web and Nexcess. Before that, Kiki was part of the Liquid Web Managed Hosting support team where she helped hundreds of WordPress website owners and learned what technical issues they often encounter. Her passion for writing allows her to share her knowledge and experience to help people. Apart from tech, Kiki enjoys learning about space and listening to true crime podcasts.