WordPress is a Content Management System (CMS) for building database-driven websites. The database-driven website architecture has existed for long enough to become the leading approach to dynamic website creation.
Most content of your WordPress website, including posts, is stored within its WordPress database, and it is of primary importance that it stays accessible at all times to accept queries and return data. In this article, we will learn how to fix the condition causing the "Error Establishing a Database Connection" message and how to restore access to your WordPress site. These steps explain how to access the WordPress database when this error condition is preventing you from connecting to it.
Overview of the WordPress database setup for content rendering
WordPress relies on database-driven website architecture, meaning your website’s database becomes the central part of the content rendering process. Your WordPress database setup works in the way that posts and some other content are written to the database rather than individual files on the disk.
Web pages are presented to each visitor by a web server after the requested data is retrieved from the database and merged with template files to generate an HTML page. This process heavily relies on the ability to establish a database connection to run SQL queries, so PHP needs to know how to access the WordPress database. PHP uses MySQL drivers like MySQLi to make database connections.
What is the "Error Establishing a Database Connection" message in WordPress?
The "Error Establishing a Database Connection" message is an error message generated by WordPress to inform the visitor that PHP failed to make a connection to the WordPress database and retrieve the requested information. As a result, no content can be displayed unless we restore the connection by addressing the underlying issue.
"Error Establishing a Database Connection in WordPress" — top three reasons why you are getting this message
As we have discussed, once WordPress fails to establish a connection to its database, no content can be presented to the visitor. Instead, the website visitor will be presented with problematic the "Error Establishing a Database Connection" message. Let’s review the three most common reasons why the WordPress database can become inaccessible. Then, further on in this article we will cover the corresponding troubleshooting steps by root cause for how to access the WordPress database as expected.
Reason #1: Wrong WordPress database credentials
Once you set up the WordPress database for the first time, you must include the database information in your WordPress configuration file. To establish a connection to the database, WordPress uses the credentials provided in wp-config.php, which contains the following information:
- Database Name. The name of your WordPress database.
- Database User. The user you assigned privileges to, so it can access the database and run queries on it.
- Database User Password. The database user’s password.
- Database Server. The database server identification to make a connection to it.
If any of the components above are missing from the wp-config.php file or have configured there incorrectly, WordPress won’t be able to establish a database connection. So you need to be extra careful putting your database information there, especially after making any changes like resetting the database user’s password.
Reason #2: WordPress database corruption
Another reason why WordPress fails to establish a database connection is database corruption. A database can become corrupt for various reasons, ranging from hardware and software failures to incorrect data removal or issues during the writing process. The key thing to understand here is that WordPress will only be able to function correctly once data integrity is restored. You can repair your WordPress database without having to restore it from a backup unless any vital information is lost.
Reason #3: Database server issues
Database server issues are the third and the most serious reason your website does not know how to access the WordPress database. When your MySQL or MariaDB database server is offline, no databases are accessible until you can get it back up and running again. The issue can be caused by a multitude of factors and is only easy to troubleshoot them with system administration skills.
The three main reasons why a database server is offline or inaccessible are:
- Your disk space usage reached 100%. Once you have reached your server’s disk capacity, all services, including database servers, will go offline until you have freed up some disk space for them to be able to write data to it.
- InnoDB tablespace corruption. InnoDB is now the default storage technology for MySQL and MariaDB. Unfortunately, corrupted InnoDB data has become a prevalent problem for server administrators — most of the time, it is caused by hardware issues.
- Too many connections. There are a limited number of concurrent connections your database server can handle using the resources available.
Other reasons behind the access issues for the WordPress database
Although the issues outlined above are the most common reasons WordPress can fail to establish a connection to the database, it does not end there. There can be situations where your WordPress database or your database server is not at fault when you are seeing the "Error Establishing a Database Connection" message on your site.
As we mentioned, PHP needs to know how to access the WordPress database. Various PHP extensions have been developed that act as relational database drivers for MySQL or MariaDB. The MySQLi extension, which stands for MySQL Improved Extension, is one of the most popular drivers to use. When it is missing from the current PHP version your WordPress site is running on, the connection to the WordPress database will fail, and you will see the "Error Establishing a Database Connection" on your WordPress site.
Other issues that are less likely to be causing the database connection errors, in particular, are having some of your WordPress core files missing or incompatible plugins and themes. So, if you have ruled out all database-related issues, but the database connection error message is still showing up on your website, you now know what other issues may need to be addressed.
How to troubleshoot WordPress database connection errors
Regarding the necessary fix for the "Error Establishing a Database Connection" condition, we need to understand what issue caused it in the first place, so we know with confidence what steps we should take to resolve it. Below we will describe the universal approach to the WordPress database connection issues resolution in a step-by-step manner.
Step #1: Verify your WordPress database credentials
The first step is to verify your WordPress database credentials and whether they match what you have put in your wp-config.php file. Manually testing the database connection can also help us rule out more serious issues like having our database server offline.
Open your wp-config.php file and examine your database credentials. You may notice that some information is missing or realize you have not updated your user’s password after having it changed:
Code snippet
// ** MySQL settings -- you can get this settings information from your web host ** //
/** The name of the database for WordPress */
define( 'DB_NAME', 'wptest' );
/** MySQL database username */
define( 'DB_USER', 'wpadmin' );
/** MySQL database password */
define( 'DB_PASSWORD', '**************' );
/** MySQL hostname */
define( 'DB_HOST', 'localhost' );
Image of code snippet
If you do not see any issues with your database information in the WordPress configuration file, you may need to test whether you can establish a database connection manually using the credentials from it.
Step #2: Test your WordPress database connection
Testing the WordPress database connection will help us check if the credentials we are using are correct and if our database server is up and running. We can do it using different ways, but the easiest and most convenient one is using SSH.
Connect to your website via SSH and navigate to your WordPress installation directory. We can use MySQL or MariaDB commands or the WordPress command line interface, as the WP-CLI provides an extensive list of tools to manage your WordPress database.
Using the WordPress Command Line Interface (WP-CLI)
Run the wp db query command to verify if WordPress can make a connection to your database using the credentials provided in the wp-config.php file. You will see one of the outputs below, letting you know if the connection was successful or not:
Code snippet
The connection was not successful
[wordpress@host html]# wp db query
ERROR 1045 (28000): Access denied for user 'wpadmin'@'localhost' (using password: YES)
[wordpress@host html]# wp db query
ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/lib/mysql/mysql.sock' (2)
Image of code snippet
As you can see, if a connection to your WordPress database fails, it can be caused by various issues. The first output tells us that we could send a request to our database server but could not get access to the WordPress database. The second error message indicates a bigger issue, as our database server was not able to receive the request, which means it is probably offline or overloaded with connections.
One vital thing to note here is that an error message saying that access to the database was denied for the user does not actually mean the password was incorrect. While it is the most common reason why you are seeing it, it can also mean that the user does not have the sufficient privilege level to access the database and run queries:
Code snippet
The connection to the database was successful
[wordpress@host html]# wp db query
Welcome to the MariaDB monitor. Commands endwith ; or \g.
Your MariaDB connection id is9508
Server version: 5.5.68-MariaDB MariaDB Server
Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.
Type'help;'or'\h'for help. Type'\c'to clear the current input statement.
MariaDB [wptest]>
Image of code snippet
Here we have successfully established a connection to our WordPress database, which means the credentials we have in our wp-config.php file are correct, the user should have all required privileges, and our site knows how to access the WordPress database.
Using MySQL/MariaDB commands
MySQL or MariaDB commands help you understand whether the database user you set up has the correct privileges to connect to the database and run queries. You can connect using the existing user and its password and then check what databases the user has access to, like shown below:
Code snippet
[wordpress@host html]# mysql -u wpadmin -p
Enter password:
Welcome to the MariaDB monitor. Commands end with ; or \g.
Your MariaDB connection id is 6
Server version: 5.5.68-MariaDB MariaDB Server
Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
MariaDB [(none)]> show databases;
+--------------------+
| Database |
+--------------------+
| information_schema |
| test |
| wptest |
+--------------------+
3 rows inset (0.00 sec)
Image of code snippet
As you can see, our wptest database is displayed among other databases. However, if our database user was not correctly added to the WordPress database, we would not see it in the list.
Step #3: Troubleshoot WordPress database connection issues
Depending on whether the database connection was successful or not, and what kind of an error message you received, we can decide what steps we will take to troubleshoot the issue.
Using the command line — WordPress database repairs if the manual database connection was successful
If the database connection you initiated from the command line was successful, the most obvious reason why your WordPress website still shows a database connection error message is database corruption. The database user can connect, but the WordPress database needs to be repaired. You can repair your WordPress database using WP-CLI commands or WordPress Admin Interface.
The wp db check and wp db repair commands — when run — can help you set up the WordPress database for the check and repair processes:
Code snippet
[wordpress@host html]# wp db check
Success: Database checked.
[wordpress@host html]# wp db repair
Success: Database repaired.
Image of code snippet
Using the WordPress Admin Interface — WordPress database repairs if the manual database connection was successful
If you want to use the WordPress Admin Interface for this purpose, add the line below to your wp-config.php file and open your-wordpress-site/wp-admin/maint/repair.php menu:
Code snippet
define('WP_ALLOW_REPAIR', true);
Image of code snippet
When the WordPress Automated Database Repair screen comes up, click the Repair Database button:
After the WordPress database has been repaired, you can remove the WP_ALLOW_REPAIR constant from the wp-config.php file. The "Error Establishing a Database Connection" message should no longer appear on your WordPress website.
Reviewing the WordPress database information and credentials — if the manual database connection was not successful
Depending on the error message you are getting while trying to connect to your WordPress database manually, you may realize WordPress is using the incorrect credentials, or your database server is inaccessible at the moment.
Access your database information in the Nexcess Client Portal or the web hosting control panel you use to verify the database credentials. You can ensure the user is correctly associated with your WordPress database and change its password if needed to update it in your WordPress configuration file:
Once the credentials in the wp-config.php file are correct, test your WordPress database connection manually. If you can connect, your website should be working again, otherwise, try to check and repair the database using WP-CLI or other available tools.
If you cannot connect to your database at all and suspect your database server is offline, it's best to contact your web hosting provider for further assistance. The root cause is most likely a server-side issue, which can be difficult to troubleshoot. We strongly recommend doing the same if you believe the PHP database extension might be missing if you have recently switched to another PHP version. A system administrator will be able to find out what exactly is causing issues and provide you with the best solution.
Conclusion with more information about WordPress hosting options at Nexcess
WordPress is a perfect content management system for building dynamic database-driven websites. But having most information stored in the database means your website relies on its content being retrieved from it to be presented to the visitors. If a WordPress database connection fails to be established, your website becomes utterly inaccessible until you address the underlying issues. Knowing how to access a WordPress database to troubleshoot connection issues is crucial to determining what exactly went wrong and how to fix it.
Exclusive WordPress management tools
- Plugin Performance Monitor
Only at Nexcess. Monitor load times and page weight with our daily plugin tester. Automatically detects performance changes when a new WordPress plugin is installed or updated.
- WooCommerce Automated Testing
Nightly testing that detects payment, checkout, and login credential problems on your WordPress site. Done in 1 minute, there’s no need to test products yourself!
Most of the time, you will need to correct your database information in your WordPress configuration file or repair your WordPress database to get your site back online. But sometimes WordPress database connection issues can be caused by a server-side problem like your database server going offline or the PHP database extension missing. We strongly recommend contacting our Nexcess Support Team to get help from our experienced system administration specialists on staff.
Nexcess provides everything you need to host your WordPress website. Our Managed WordPress hosting plans are fully optimized for the platform to make your site faster, more secure, and protected from various issues. Our technical team consists of the best web hosting experts with extensive knowledge of WordPress and other popular CMSs. All the best solutions from the world of WordPress combined with years of experience the Nexcess team has working with the platform make Nexcess the web hosting provider of choice.
Recent articles
- Using Local (localwp.com) for local WordPress development
- How to view your Nexcess account ID number and account PIN number
- Magento or Flex Cloud plan — how to set email password
