Everyone’s heard of it, and some of them have crossed paths with it, and eventually, so will you. What we are referring to is the white screen of death in WordPress, more commonly known as, “Error establishing a database connection”.
Before you start panicking and imaging the worst-case scenario, most often your data is safe and sound. The data is there, but something is preventing the website from accessing it from the database. In this article, that is exactly what we are going to tackle. We will be exploring the WordPress database, what actually causes the error in establishing a database connection in WordPress, and how to solve it.
The WordPress Database Explained
Every WordPress website is made up of two essential parts-
- The Core files
- The Database
Firstly, the WordPress core files are needed for the proper installation and everything else. There are various folders and other files that play a key role during the installation and after the setup process. The WordPress core files are written in PHP language.
Now before moving to the database, we need to cover what data is first. Data refers to information about a particular topic, situation, or person that can be collected and stored in different formats. We can store the collected data in various formats such as documents, images, videos, etc. As the data increases, keeping everything organized and accessing it quickly can get tricky.
This is where databases are helpful. A database is where we can store all the information in an organized manner that allows for easy retrieval at any given point in time. This is what is most important, the data is stored in an organized manner and not randomly and can be retrieved instantly. The data from any point in time can be recalled in the shortest possible time.
The data that is stored in the database will most often undergo changes on a regular basis, which includes adding new data and removing redundant data. The data is stored in tables, rows, and columns. Every time a user visits your website, the relevant data is fetched from the database.
Now a database is used for storing and retrieving the relevant information. But how does one interact with the database? The interaction with the database is made possible with a Database Management System (DBMS).
Ok, so a database is used for storing data and we access it with a DBMS. Now let’s view the database from a WordPress point of view. Let’s start with the data, or more precisely what all data is stored in the database. The data that is stored in the WordPress database includes:
- The website settings (login credentials of both the users and the admins, URLs)
- Theme and plugin data, most often their configuration
- Data related to the post, pages, tags, categories, comments
As we mentioned a few paragraphs above, every change you make to the website is reflected in the database. It can be the addition of a new URL, new user comments, changes to your post or pages, and so on. By default, the WordPress database comes with 12 tables in which the data is stored and they are:
- wp_commentmeta- Stores the metadata of each comment.
- wp_comments- data related to the user comments on the website are stored in this table.
- wp_links- The purpose of this table was to store information related to the Links feature which is now deprecated.
- wp_options – the website configuration data is stored here.
- wp_postmeta – stores the metadata of each post.
- wp_posts – stores the data of both the posts and pages.
- wp_terms – saves the information related to the categories and tags.
- wp_termmeta – saves the metadata of each term.
- wp_term_relationships – is responsible for maintaining the relationship between posts and taxonomies.
- wp_term_taxonomy – stores the description for all the taxonomies on the website.
- wp_usermeta – includes all the metadata of the registered users.
- wp_users – includes all the user information such as passwords, usernames, and email accounts.
Each table has specific duties which are evident from their title. Each table includes multiple columns and fields in which data is arranged. For example, if we take a look at the wp_usermeta table we can see the following columns:
umeta_id
user_id
meta_key
meta_value
Now, we need to know how the communication to the database is established. WordPress uses MySQL as its DBMS. MySQL is an open-source relational database system and uses Structured Query Language. With every WordPress installation, we require a database with a username and password. The process of creating a database will vary, depending on how you are installing WordPress either manually or through the host.
The MySQL query part is taken care of by WordPress every time there is a need to store, rewrite or recall data from the database. In almost all cases, the website and the database are stored on the same server. The WordPress database can also be referred to as MySQL database.
But if needed, you can also run the MySQL commands manually, but to do that you need to access the database first. The way to access the database is from your hosting account control panel. Once there you need to head over to phpMyAdmin.
You will have to enter your login credentials if asked for and once you do it, you can access the database.
Here, we can see all the default database tables we discussed earlier.
You can make changes to each table as you want but make sure to make a backup before you start making any changes to be on the safe side.
If you need to run SQL queries manually, you can do this from the SQL tab.
Top Factors That Cause Error Establishing a Database Connection Error in WordPress
If you are faced with this error, what this means is that the communication to the WordPress database is broken. Every time a user enters your website URL, the PHP codes work behind the scenes, send a query to the database to pull the relevant data, and finally deliver it to the user.
But sometimes, due to certain factors, the communication between the PHP and the database will fail. It is when this handshake between the PHP functions and database fails, that results in establishing a database connection error in WordPress.
The top reasons that can lead to this error are:
Incorrect database login credentials
In most cases, the reason why this error occurs is due to the wrong WordPress database login credentials. If the login details are wrong, then there is no way to access the database and retrieve the data to complete the query.
Lack of user privileges
Even if all the login credentials are correct, the database user may not have the right set of privileges. Not having the privileges permission set to “All Privileges” can also lead to this error.
Corrupted database
The next possible cause of the error is the database itself. A lot of factors can corrupt the WordPress database such as server issues, updates to WordPress itself, malware, and so on.
Plugin and theme related issues
Updates to plugins and themes can also cause this error. If so finding the root cause is easy, which we will discuss shortly.
Issues with the core files
The core files can also get corrupted. From hackers to updates to WordPress malware infections and other compatibility issues can corrupt the core files.
Problems with the database server itself
Sometimes, the issue might be with the server hosting the WordPress database. The server may have faced downtime and in such cases contacting the host and waiting for the server to come back online is the only way forward. Issues that cause server downtime can be a sudden surge in traffic which is a common scenario for shared hosting website owners and hardware failures.
How to Fix the Error Establishing a Database Connection in WordPress
Now that we know the common causes behind this issue, it’s time to look at how to actually solve the issue. Before you start making the changes, make sure to take a complete WordPress backup, to ensure you don’t lose any data.
Verify Your Database Login Credentials
The first thing to do is to make sure that the login credentials to the WordPress database are correct. If the login credentials are wrong, then there is no way the website can access the WordPress database. The database login credentials can be found in the wp-config.php file. You can access this file via FTP or from the file manager in your hosting account.
This is how the content of the file will look.
The login credentials that we need to verify are:
- DB_NAME
- DB_USER
- DB_PASSWORD
- DB_HOST
For cPanels to confirm the database name, head over to phpMyAdmin and confirm whether the database name is correct and matches the credential in the wp-config.php file.
To verify the DB_USER, cPanel users can do this by accessing MySQL Databases.
Once you access this you can verify whether the DB_USER is the same as the one in the wp-config.php file. If not correct it. If the DB_USER and DB_NAME are correct and still the error persists, it is time to create either a new user or change the password for the existing user and try again. cPanel users can do this from the MySQL Databases section itself.
cPanel doesn’t provide the option to view the current password of existing users as of now and creating a new one is the only option. Once you make the changes, update the new credentials in the wp-config.php file.
Most of the hosting companies do use localhost for DB_HOST, but if you are not sure, you can contact your hosting service provider and re-confirm it.
Double-check User Privileges
Now, the username, password, and database name would have been correct, but the user may not have all the privileges. If the user doesn’t have the privileges, then accessing the data will not be possible.
To edit the privileges, access the user from the MySQL databases and click on the username
After you have selected the user, update the privileges and save the changes
Try to load the website and see if everything loads up properly. If it does, then not having the proper privileges was the issue.
Corrupted Database
We can repair the WordPress database in three ways. We can do it from the wp-config.php file, from the hosting account control pane, and also from phpMyAdmin.
To repair the database from the wp-config.php file, all we need to do is to add the following line of code:
define('WP_ALLOW_REPAIR', true);
Now go to yourwebsiteaddress.com/wp-admin/maint/repair.php to start the database repair process. Once you do it you will be presented with the following screen.
You can choose to either just Repair Database or Repair and Optimize Database. Once the repair process is done, try to load your website and see if everything is back to what it was. Remember to remove the added code snippet from the wp-config.php file after the repair process.
Now to repair the database from the hosting control panel, cPanel users can do it by accessing MySQL databases and selecting repair database.
If you prefer to repair the database from phpMyAdmin, all you have to do is select your database and choose Repair Table. You can either repair all the tables or choose to prefer do them one by one.
Troubleshooting Plugin and Themes
New updates to plugins and themes on rare occasions can lead to problems, and if you doubt one of the recent updates caused the issue this is how you can troubleshoot it.
Firstly we will focus on the plugins. Access your site’s files via FTP and rename the plugins folder to anything you want to deactivate all of them at once.
Now try loading your website and see if it is back online. If so you know the issue is in one of the plugins. To find the plugin throwing the error, you need to rename this folder back and then start renaming each plugin folder to a random name till you find the faulty one.
You can deactivate all of your installed plugins or individual ones from phpMyAdmin also. To do this head over to phpMyAdmin and locate the wp_options table in your database. Now locate the row titled active_plugins and remove the data in option_value. This will deactivate all of your plugins.
Now to deactivate individual plugins, you need to take a look at the data and find the individual plugins. This will be a time-consuming process and the best way to deactivate plugins will be from FTP.
To deactivate your theme, rename your active theme folder to any name you want. Doing this will only show you a white screen and won’t display any content but will give you access to wp-admin which in turn tells us that the issue was indeed the theme.
If needed, you can also change the theme to a default one from phpMyAdmin. For that head to phpMyAdmin and select the right database and navigate to wp_options. Then search for two rows titled- template and stylesheet.
Once you find it, change the option_value of both rows to another default theme, like Twenty Twenty, and save it.
Fix the Corrupted WordPress Core Files
The WordPress core files can get corrupted from a malware infection and so on. If you suspect your core files are corrupted the best method is to replace them completely. To replace the files download a new copy of WordPress and unzip the files.
Now, delete the wp-content folder and upload the remaining files and folders via FTP and overwrite the existing ones. If the corrupted core files were causing the issue, then this will solve it.
Check if Your Database Server is Offline
Sometimes, the root cause will be the WordPress database server itself. The server may be experiencing downtime due to an increase in traffic and if you opted for shared WordPress hosting, then another website on the server is hogging up all the resources or the server may have faced technical issues.
The best way forward in such a scenario is to contact your web host for further assistance.
Wrapping Up
Establishing a database connection error in WordPress can be caused by multiple factors. If you ever face this error, follow the above-mentioned steps to solve the issue to get your website back online.