Any technical error that occurs on your website can be scary, but the error establishing a database connection error is among the scariest. That's because this error blocks access to your entire website and replaces it with a blank screen that simply says error establishing a database connection in bold, black text. But what exactly does this error mean and how to fix it?
Solving this issue can be tricky. This is because it can be caused by a number of different things, so it can require a great deal of troubleshooting. If you're a developer or even an experienced WordPress user, you won't likely have a tough time figuring out what's causing this issue.
If you're a blogger or business owner in charge of running their own website, don't worry. We're going to walk you through the process of figuring out what's causing the error establishing a database connection issue on your site. Let's get started.
- What does Error Establishing a Database Connection mean?
- What causes Error Establishing a Database Connection in WordPress?
- Attempting to repair the database
- Enabling WordPress' built-in database repair tool
- Fixing login credentials
- Consulting your hosting company
What does Error Establishing a Database Connection mean?
If you're an experienced developer, feel free to skip this explanation, and head to the what causes this issue and how to solve it sections instead. We're going to briefly explain what a database is so general users can have a better understanding of what the error establishing a database connection issue is.
Most WordPress websites are comprised of two basic elements, which are PHP and MySQL. PHP is a free and open-source scripting language for web development. MySQL is a Relational Database Management System that uses Structured Query Language. Some hosts and developers use alternative tools to manage their databases, such as MariaDB and PostgreSQL.
PHP is part of what you use (or the developers of the WordPress themes and plugins use) to code your website and make it look and behave the way it does. A database is what you use to store and manage your site's data, such as your posts, users and comments. You can perform critical administration tasks, such as backups, performance monitoring, recoveries and more.
The database is arguably the most important element of a website's infrastructure as a WordPress site can't function properly without it. Hence, you're seeing an error establishing a database connection message instead of your website if there is an issue with your database. Let's talk about why there might be a problem with the connection between your website and your database.
What causes Error Establishing a Database Connection in WordPress?
There are a number of different reasons as to why you're experiencing an error establishing a database connection issue. Here are the most common causes:
- Incorrect database credentials
- Corrupted database
- Corrupted file(s)
- Server issues
Incorrect database credentials – Your database uses a specific set of login credentials that must be defined in the wp-config.php file of your WordPress site. If one of these credentials is incorrect, it may produce the error establishing a database connection message on your site.
Corrupted database – Your database can become corrupted by a number of different things, such as a faulty plugin you installed or an interruption during a data transfer. Your site usually may not be able to connect to the corrupted database if this is the issue.
Corrupted file – There are also a number of different things that can cause your files to become corrupted in WordPress. These include your file permissions being set up incorrectly, a firewall (from your site or server) blocking specific sections of your site, an incorrect URL on the General Settings page, etc. There are numerous of other reasons, but we'll get to them in a bit.
Server issues – Hardware failures and DDoS attacks do happen, and they'll take your database down with them when they knock out your server. Your site may produce the error establishing a database connection message when this happens.
Let's switch gears yet again and talk about how to solve each of these issues.
Attempting to repair the database
You may be seeing more than just the error establishing a database connection message, or you may only be seeing it in certain places. You likely have a corrupted database if any of these apply:
- You're able to visit the frontend of your website, but you see the error message when you you visit /wp-admin/.
- Your site is down, and you're seeing other error messages as well, such as one stating your database tables are unavailable.
These types of behaviors are indicative of a corrupted database. Thankfully, WordPress has a built-in tool you can use to repair the database with little involvement on your part. It may be a little tricky for some, especially if you've never accessed the file system of your site.
Enabling WordPress' built-in database repair tool
Open your site's file system. Most hosts use a control panel called cPanel. Open cPanel, and scroll down until you find an app called File Manager. Use it to open your site's root folder, which is typically public_html. You can also access your site's file system via an FTP client, such as FileZilla.
Once you've found your site's root folder for WordPress, open a file called wp-config.php in a text editor. You may need to download it first. Once you do, add this bit of code to the bottom of it:
Add it above the That’s all, stop editing! text. Feel free to include a descriptive comment above it. Just be sure to use /* and */ so it's treated as comment and not interpreted as code.
Save the file, and re-upload it to your root folder. With the WordPress' built-in database repair tool enabled, you can access the database repair screen. Enter this url in the address bar of your browser:
Make sure you replace www.example.com with your own domain. Once you do, you should see this screen with further instructions:
Choose the Repair Database option. The second option, Repair and Optimize Database repairs your corrupted database before optimizing it by doing a bit of spring cleaning. This can help improve site speed. You can select the Repair and Optimize Database option if you want to, but adding optimization to the process makes the repair much longer to complete.
Fixing login credentials
Your database's login credentials must be correct, as stated before. If the login credentials are incorrect you'll see an error establishing a database connection message across your site. When you switch hosts, these login credentials will likely change in your database. Your wp-config.php file needs to be updated manually to reflect those changes. This issue can also occur if you recently changed your database name, password or anything else that is needed to access your database.
Basically, what you need to do is make sure the login credentials in your wp-config.php file match your actual credentials. You can try to hunt down your login credentials through phpMyAdmin, but it may be much more efficient to simply ask your host what the credentials are. Make sure the following settings match the credentials your host gives you:
These are the top four settings that are most likely to produce the error establishing a database connection issue on your site. If you need to make changes to one of these settings in your wp-config.php file, save it, and re-upload it to your site's root directory.
Consulting your hosting company
If all else fails, repairing your database did nothing, your login credentials are correct and there are no corrupted files on your site, it may be time to consult your hosting company. If your host is experiencing some type of outage due to a hardware or software issue or even a nasty DDoS attack, your site will go down with it. They may even be a small possibility that your site has been hacked.
There's nothing you can do if this is the case as your host will need to determine how to get the server back up. This is why it's important for you to consult your host if you see an error establishing a database connection message on your site so you can see if this is what's causing the issue.
Final thoughts on fixing this issue in WordPress
The error establishing a database connection issue can be scary, but we hope we made tracking down the cause of this issue a little simpler for you. Troubleshooting can also be a difficult and frustrating process to go through. This especially can be the case if you're not experienced with WordPress or web development as a whole. Just remember to try these solutions:
- Try to use WordPress' built-in repair tool to repair the database.
- Consult your hosting company, ask them for the login credentials to your database, and see if they match the credentials listed in your wp-config.php file.
- Consult your host to see if your server is down and producing this error message.
It may be difficult to prevent this issue from occurring in the future. But you can protect yourself by backing up your site on a regular basis and creating restore points you can use in cases like these. If you don't want to do these things yourself, check to see if your host offers these services, or switch to a hosting company that does. Have you ever experienced this issue and do you have any additional tips or suggestions? Please let us know in the comments below.