Fixed: “Error establishing a database connection”

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:

// ** 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' );

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:

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)

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 is a critical error message indicating 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:

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]>

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:

[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)

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:

[wordpress@host html]# wp db check
Success: Database checked.

[wordpress@host html]# wp db repair
Success: Database repaired.

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:

define('WP_ALLOW_REPAIR', true);

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 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.