How to Fix Error establishing a database connection in WordPress?

WordPress is simple to use software when installed properly. however, it will though different types of error while installation and accessing the site if you do not follow the correct process. “Error establishing a database connection” in WordPress is one of the frequently seen error users see after installing a new site. if you stuck with this error, here is how you can fix and restore the access to dashboard and frontend.

What is this Error About?

Before going further, it is necessary to understand some basic things about how WordPress works. Here are the three types of files that make WordPress to work properly and show the layout when you open a page in the browser. Missing one of these things will result in PHP errors or the complete page is showing as blank called white screen of death.

• Core WordPress PHP files – these are the files part of WordPress software which you can download for free from WordPress.org site.
• Backend database, generally created in MySQL – your database will be created during installation process.
• Your themes and plugin files – you can install and update themes and plugins from the administrator panel.

The first step is in WordPress installation is to create database with username and password and provide correct privileges. Then you can connect this database to WordPress core files using the username/password. After installing WordPress and connecting to a database, you can use administrator username/password to login to the dashboard section and start building your site.

Nowadays, most of the hosting companies like SiteGround use one-click WordPress installation process. During this process, system will automatically create database and connect the database to your WordPress installation. Though it makes the life easier, it hides the fact that there is a database behind the WordPress installation. However, you can clearly understand this process while installing WordPress manually on localhost or using apps like Softaculous in cPanel.

Error establishing a database connection

This error occurs when you try to open dashboard or one of the pages in your site. However, WordPress could not connect to the backend database and throw an error indicating the connection can’t be established.

If you see this error, most probably you are trying to install WordPress manually. It could be on the live server, or on localhost or on a stagging site.

Fix Error Establishing a Database in WordPress

Now that you understand why the error occurs. It’s time to understand a bit more to get the origin of this error. As mentioned, WordPress contains core PHP files that includes configuration and other setup for your site to run properly. The most important configuration file is wp-config.php which will be available along with other core installation files in root installation directory. Your database username/password are stored in this wp-config.php file and WordPress uses these details to fetch the data from your database. So, it is clear that the wrong database username or password in wp-config.php file is the root cause of “Error establishing a database connection” error.

Getting Username and Password of Your Database

To fix this error, you first need to get the correct username/password of your database and update in wp-config.php file. Here we will explain with cPanel from HostGator and the process remains similar for any other cPanel hosting company. If you are using custom hosting panel like in case of SiteGround, still the process is same except that you will find the details in custom interface instead of cPanel

• Login to your hosting account and access cPanel.
• Search and open “MySQL” or “MySQL Databases” app.

• MySQL Databases app will show the details of your existing databases and username along with an option to creating new items. Remember, phpMyAdmin is the tool for managing your database content like viewing, importing and exporting. However, you can’t find the database username and password in phpMyAdmin and need to go to MySQL section for that purpose.
• Check the list of current databases and note down the name of your database.

• Also, note down the username from the list (in cPanel, you can find these details under “Current Users” section).

• If you do not know the password, click on “Change Password” option and reset the password for your database.

Updating Details in wp-config.php File

Now that you know the credentials of your database, go back to cPanel. Search and open File Manager app in your hosting panel.

Navigate to public_html section and locate wp-config.php file. Select the file and click on “Edit” option. Remember, WordPress also comes with a sample configuration file named as wp-config-sample.php. Make sure to select the real wp-config.php instead of mistakenly editing the sample file.

It will open a pop-up and ask you to backup the file before editing. If required, you can download and keep a backup for restoring purpose. Otherwise, click “Edit” button to proceed further (note that this step is not needed in most of the custom hosting panels).

You will see the file open in an editor and after initial comments section, you can see a comment like “// ** MySQL settings – You can get this info from your web host ** //”. Below that comment, there will be four define commands to link your database details.

• Below the comment “/** The name of the database for WordPress */” you can find the line like define( 'DB_NAME', 'abcd_1234' );. In this comment, replace the database name abcd_1234 with your database name note down in the previous step.
• Similarly change the database username and password details in the corresponding define commands.
• Finally, leave the DB_HOST parameter as localhost.

Here are the details you should change:

After changing the details, save your changes and try to access your admin dashboard or any other page of your site. now, you should see the site loads properly without “Error establishing a database connection” error.

Warning: Make sure to edit wp-config.php with correct details and do not delete any single quote. All parameters should be typed within open and close single quote, mistakenly deleting a quote will show a white screen or another PHP error.

Sample wp-config.php File

Below is the sample wp-config.php file that comes with default WordPress installation. We have given this here for a reference for you to understand how it looks and find the details to be updated.

<?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';