How to fix an Error Establishing a Database Connection

A WordPress installation is comprised of files and a database which work together to deliver a unique website to its visitors. The files of a WordPress site contain the code necessary for the installation to function; items like the code of plugins and themes are stored in the file structure. The database is also a crucial working part as it contains the unique information that makes items like pages and users deliver the correct information to the end user. It organizes the data of each site and is considered dynamic, which means it is ever changing based on the values/updates the WordPress admin makes.

Without proper connection to the database, a WordPress site will load to the error ‘Error Establishing a Database Connection‘. This error looks like this:

The two most common reasons this can occur are:

1. Incorrect connection strings in the wp-config.php file
2. The WordPress database does not exist
3. The MySQL service is down

Scenario #1 & #2 are the more common of the three. Checking the connection strings is the first recommended step to take when troubleshooting this error. Let’s dive into what the wp-config.php file looks like and how to make sure the connection strings are correct.

#1: Checking the connection strings in the wp-config.php file

The WordPress file structure uses a crucial file called wp-config.php to connect to the database. Without this file, the site will not load. This file is found in the webroot installation like so:

The code of this file looks similar to this:

<?php
/**
 * The base configuration for WordPress
 *
 * The wp-config.php creation script uses this file during the installation.
 * You don't have to use the web site, you can copy this file to "wp-config.php"
 * and fill in the values.
 *
 * This file contains the following configurations:
 *
 * * Database settings
 * * Secret keys
 * * Database table prefix
 * * ABSPATH
 *
 * @link https://wordpress.org/support/article/editing-wp-config-php/
 *
 * @package WordPress
 */

// ** Database settings - You can get this info from your web host ** //
/** The name of the database for WordPress */
define( 'DB_NAME', 'database_name_here' );

/** Database username */
define( 'DB_USER', 'username_here' );

/** Database password */
define( 'DB_PASSWORD', 'password_here' );

/** Database hostname */
define( 'DB_HOST', 'localhost' );

/** Database charset to use in creating database tables. */
define( 'DB_CHARSET', 'utf8' );

/** The database collate type. Don't change this if in doubt. */
define( 'DB_COLLATE', '' );

/**#@+
 * Authentication unique keys and salts.
 *
 * Change these to different unique phrases! You can generate these using
 * the {@link https://api.wordpress.org/secret-key/1.1/salt/ WordPress.org secret-key service}.
 *
 * You can change these at any point in time to invalidate all existing cookies.
 * This will force all users to have to log in again.
 *
 * @since 2.6.0
 */
define( 'AUTH_KEY',         'put your unique phrase here' );
define( 'SECURE_AUTH_KEY',  'put your unique phrase here' );
define( 'LOGGED_IN_KEY',    'put your unique phrase here' );
define( 'NONCE_KEY',        'put your unique phrase here' );
define( 'AUTH_SALT',        'put your unique phrase here' );
define( 'SECURE_AUTH_SALT', 'put your unique phrase here' );
define( 'LOGGED_IN_SALT',   'put your unique phrase here' );
define( 'NONCE_SALT',       'put your unique phrase here' );

/**#@-*/

/**
 * WordPress database table prefix.
 *
 * You can have multiple installations in one database if you give each
 * a unique prefix. Only numbers, letters, and underscores please!
 */
$table_prefix = 'wp_';

/**
 * For developers: WordPress debugging mode.
 *
 * Change this to true to enable the display of notices during development.
 * It is strongly recommended that plugin and theme developers use WP_DEBUG
 * in their development environments.
 *
 * For information on other constants that can be used for debugging,
 * visit the documentation.
 *
 * @link https://wordpress.org/support/article/debugging-in-wordpress/
 */
define( 'WP_DEBUG', false );

/* Add any custom values between this line and the "stop editing" line. */



/* That's all, stop editing! Happy publishing. */

/** Absolute path to the WordPress directory. */
if ( ! defined( 'ABSPATH' ) ) {
	define( 'ABSPATH', __DIR__ . '/' );
}

/** Sets up WordPress vars and included files. */
require_once ABSPATH . 'wp-settings.php';

This file has connection strings that tell the files what data to use to connect to which database. In most cases, the database is stored on the same server the files are stored on. Sometimes larger sites may have a database stored on another server completely which will require a different set of connection strings to properly connect the files to the database. The connection strings are these values here:

// ** Database settings - You can get this info from your web host ** //
/** The name of the database for WordPress */
define( 'DB_NAME', 'database_name_here' );

/** Database username */
define( 'DB_USER', 'username_here' );

/** Database password */
define( 'DB_PASSWORD', 'password_here' );

/** Database hostname */
define( 'DB_HOST', 'localhost' );

The four values connect the WordPress files to its database. The database name, database user, database password, and database host. These values are created when the WordPress installation are created. If these values have any incorrect data in them, your WordPress website will load to the error, ‘Error Establishing a Database Connection’.

In order to check these values, you will need access to your web hosting account. Your hosting provider may also be able to check these for you. If you would like to review these yourself, log into your hosting account and navigate to where the database information is stored. We will use cPanel as an example.

Open your cPanel account and navigate to MySQL Databases underneath the section Databases:

After selecting MySQL Databases, your view should look similar to this:

First, make sure the database name in your wp-config.php file matches the database name listed in cPanel. The database name is this value here:

Make sure to copy this value exactly and paste it into your wp-config.php file where the database name here value is in a sample wp-config.php file:

define( 'DB_NAME', 'database_name_here' );

This database example will look like this:

define( 'DB_NAME', 'i8976919_wp1' );

Next, make sure the database username is correct. You will also find this information within your cPanel account. Simply scroll down to the bottom of the MySQL Database page until you see Current Users at the bottom, like so:

Make sure to copy the user exactly as shown into the database user section in your wp-config.php file. The section in the sample wp-config.php file looks like this:

define( 'DB_USER', 'username_here' );

Using this database example, the value will look like this:

define( 'DB_USER', 'i8976919_wp1' );

Next, the database password will need to be checked. For security purposes, this password is not viewable on cPanel – the only way to check this value is to change it in cPanel and also change it in the wp-config.php file. You can do this by selecting Change Password under the Actions section underneath the Current Users:

After changing the password, make sure to update the wp-config.php file database password section here:

define( 'DB_PASSWORD', 'password_here' );

Make sure the password is very secure. You can use the cPanel password generator or a third party option like LastPass.

The last value to check is the database host value. In the wp-config.php file, this section looks like this:

define( 'DB_HOST', 'localhost' );

cPanel, along with other hosting GUIs use the value localhost, but this value varies based on your hosting provider. You can visit this comprehensive list organized by hosting provider to see what your database host value should be. You can also verify this value with your hosting provider if they are not on the list.

After each connection string value is checked and fixed, save the wp-config.php file and reload your site. In most cases, this should fix the ‘Error Establishing a Database Connection‘ error. If your site is still loading to this error, make sure all caches are cleared. If the site is not cached, the MySQL service may be down. Let’s move on to scenario #2 to review this further.

#2: Verify the WordPress database exists

It is more common for a WordPress database to be hosted on the same server where the files exist. There are some sceanrios where a WordPress database is hosted on a separate server, but this is usually applicable for larger sites. During a standard installation process, when WordPress is being created on a server, the database is generated on the same server the files live on. It is easy to verify if the database exists on many hosting plans, as you can navigate to the server’s database section and check to make sure your database is there. Let’s take cPanel for example:

To verify the WordPress database exists on a cPanel, navigate to MySQL Databases and check under Current Databases. If there are no databases on your server, you will see the following:

If there are no databases on your hosting server, you will need to create one that matches the name of the database name in your wp-config.php file and restore its data from a backup.

#3: Checking the MySQL Service

In rare instances, the MySQL service may be down. Without this service properly running, the files will not be able to connect and load the database. To verify that the MySQL service is running, first find what type of hosting your WordPress is running on. Most WordPress sites are hosted on shared hosting environments and your hosting provider will assist you on getting the MySQL service back up and running again. If your website is hosted on a Virtual Private Server (VPS) or a Dedicated Server, you will be responsible for making sure the MySQL service is running properly. You will have control over this service on a VPS or Dedicated Server, while on a shared hosting server you typically do not have control over this service.

If your WordPress site is hosted on a shared environment and you believe the MySQL service is down: Contact your hosting provider to assist you with getting this service back up.

If you WordPress site is hosted on a VPS or Dedicated Server, you will need to troubleshoot and fix the MySQL service yourself.

Troubleshooting the MySQL service will require server administration knowledge. Here are a handful of commands you can run on a Linux based hosting environment to help get you started on troubleshooting the MySQL service:

Checking if the MySQL service is running on a server

Checking the MySQL service will require SSH access. The command you run will depend on the distribution of Linux your server is running. Sometimes the MySQL service will be named differently as well. For example, some systems use the service name mysqld, while others use mysql. To check the status of the MySQL service, you can run this command:

sudo systemctl status mysqld

You can also try this command:

sudo service mysqld status

If the MySQL service is running, the output will display that it is Active (running). If the service says anything other than active, your server administrator will need to troubleshoot the MySQL service further.

Error Establishing a Database Connection Guide Wrap-Up

In this guide we reviewed the three most common scenarios as to why a WordPress site might succumb to an ‘Error Establishing a Database Connection‘ and how to resolve them. To summarize, here are helpful tips to remember when troubleshooting this error:

• Incorrect connection strings in the wp-config.php file is the most common reason this error occurs. Review this section first!
• Many hosting providers have different values for the database host section. Consult with your hosting provider if you are unsure of this value.
• While uncommon but still possible: The MySQL service may be inactive which can cause this error. Team up with your hosting provider to ensure the service is running if your site is on a shared hosting platform, or team up with your server administrator if your site is hosted on a VPS or Dedicated Server.