How to Fix the Error Establishing a Database Connection in WordPress

Do you see an ‘Error establishing a database connection’ in WordPress? This is a fatal error because users can’t use your site. It occurs when WordPress is unable to establish a connection with your database. The reason could be rooted deep, since several things can affect this connection; thus, it’s pretty hard to troubleshoot for beginners.

In this article, we will explain how to fix ‘Error establishing a database connection’ easily on your WordPress site, step by step.

What is a Database?

A database is software that bridges other software for easy storage, organization, and retrieval of data. Now, WordPress, as a content management system, has a database wherein it stores all your content and any other data related to your website. Hence, it connects to the database every time somebody accesses your website.

Why Does the Error Occur?

This information is stored in your WordPress configuration file called wp-config.php. If any of this information is incorrect, then WordPress is not able to connect to your database server, and you will see the ‘Error establishing a database connection’ error.

Step 1: Check Database Login Credentials

If you’ve just moved your WordPress install between servers or hosting providers, you may need to update your database connection details. These are stored on the server in a PHP file called wp-config.php.

First of all, let’s find our wp-config.php file:

sudo find / -name "wp-config.php"

This searches everything from the root directory (/) down, and finds any file named wp-config.php. If such a file exists, the full path will be output:

Output /var/www/html/wp-config.php

Now use your favorite text editor to open the config file. We’ll use the nano editor here:

sudo nano /var/www/html/wp-config.php

This will open a text file full of configuration variables and some explanatory text. Up towards the top is our database connection information:

/** The name of the database for WordPress */
define('DB_NAME', 'database_name');

/** MySQL database username */
define('DB_USER', 'database_username');

/** MySQL database password */
define('DB_PASSWORD', 'database_password');

Check that these three variables are correct based on your records. If they don’t look right, update as appropriate, save and exit (CTRL-O, then CTRL-X if you’re using nano).

Step 2: Check if MySQL is Running

A good first step for debugging this problem is to try logging into the server to see if the system is healthy and MySQL is running. Log into your server via SSH, remembering to replace the highlighted portions below with your own user and server details:

ssh sammy@your_server_ip

If you need help logging into your server, please see our article How To Connect To Your Droplet with SSH.

Now that we’ve logged in successfully, let’s check that our MySQL server is running:

sudo netstat -plt

The netstat command prints information about our server’s networking system. In this case, we want the names of programs (-p) listening for connections (-l) on a tcp socket (-t). Check the output for a line listing mysqld, highlighted below:

Output
Active Internet connections (only servers)
Proto Recv-Q Send-Q Local Address Foreign Address State PID/Program name
tcp 0 0 localhost:mysql *:* LISTEN 1958/mysqld
tcp 0 0 *:ssh *:* LISTEN 2205/sshd
tcp 0 0 localhost:smtp *:* LISTEN 2361/master
tcp6 0 0 [::]:http [::]:* LISTEN 16091/apache2
tcp6 0 0 [::]:ssh [::]:* LISTEN 2205/sshd
tcp6 0 0 ip6-localhost:smtp [::]:* LISTEN 2361/master

Step 3: Check Database Permissions

After that, click the ‘Manage’ button next to the phpMyAdmin section.

This will open phpMyAdmin in a new window, where you must click the ‘Database’ option at the top.

After that, click on your database’s name to access its settings. If you can do that, then it is time for you to check if your database user has sufficient permissions.