Easy Fix to Error Establishing a Database Connection

The Error establishing a database connection is most often connected to manual installation or migration of a WordPress site but can rarely occur as a result of human or technical errors under normal website maintenance. While new users can easily panic over the white screen with a big error warning, it is for the most of it nothing to worry about.

This post will help you understand the reasons behind the Error establishing a database connection notification and will guide you to simple fixes. The fixes are divided by specific error type and not by occasion due to the fact that each of them can occur in almost any situation.

When troubleshooting the Error establishing a database connection, it’s recommended that you go through the list of possible causes/checks/fixes in the order they are listed in here. The list starts from the most common errors and goes on to the rarer causes and solutions.

Missing Permissions

One of the most common reasons behind Error establishing a database connection is missing permissions. This type of error occurs due to forgetting to create and assign a user to the database or giving it not enough rights. Such errors occur most often in connection to manual installation of WordPress or migration to a new host. In rare cases it can be the result of accidentally deleting/limiting the rights of the user, while performing other maintenance tasks.

To check, whether the error is caused by missing user permissions or not having assigned a user to your database at all, you have to do the following:

1. Log into cPanel on the server (or your alternative control panel)
2. Navigate to the MySQL (cPanel) or Databases icon and click on it
3. On the next screen, you should be able to see a form for creating new databases, a tool for assigning users to databases, and an overview of your existing database(s) and their assigned users, as shown on the screenshot below.
4. Firstly, make sure that there is a user assigned. If there isn’t a user assigned, the field under Privileged Users would be empty. In case it’s empty, use the Assign user to database tool on the same screen to assign a user and give it privileges.
5. Secondly, if there is a user assigned to the database, the Error establishing a database connection issue is likely caused by missing permissions. Simply click on the user name (encircled in the screenshot). Next, you’ll see a list of available and given privileges. Check them all and save your settings.
6. If some privileges were missing, this can trigger an Error establishing a database connection notification. Once you have changed your settings, check whether the issue persists.

This solves the error in most cases. There are, however, also other causes to it, so, if the fix above didn’t work, just keep reading.

Misspelled Database Name, User, and Pass

To connect the database with the WordPress installation, you have to enter the database credentials into the wp-config.php file. You have to do that both when manually installing WordPress and when migrating an existing website from one webhost to another.

The reason is that, when manually installing WordPress, wp-config.php doesn’t get automatically generated as in the case of one-click installs. Therefore, you have to manually get in, rename wp-config-sample.php to wp-config.php and enter the database name, database user, and user password. You have to also check whether the HOST value should be localhost or a custom value (your web host can help you with instructions).

When migrating to a new host, you have to go through the manual database setup once again. This results often into errors, such as forgetting to change that database name or user values.

The solution is simple:

1. In the File Manager on the server, locate the directory public_html (some hosts allow you to only view the contents of this folder, so if you can’t find public_html, you are likely already in it).
2. Click on it to view its contents
3. You should be able to see the three WordPress core folders: wp-admin, wp-content, and wp-includes, as well as many loose files.
4. Find wp-config.php (if you are performing clean install of WordPress, you are looking for the file wp-config-sample.php that you must edit and rename to wp-config.php) and open it, either directly on the server (using the Edit file function) or by downloading and opening it in a text editor locally.
5. Find the MySQL settings, shown in the screenshot below. MySQL is short for the database.
6. When you created the database, you hopefully noted the database name, user, and pass. Check for misspellings. Keep in mind that an extra empty space or wrong punctuation also give an error! If possible, always copy-paste database credentials to avoid errors.
7. If you haven’t noted down the database credentials, you can always find the database name and user on the MySQL screen (or Databases) in your control panel on the server. Often, you can also directly get the user pass from the existing users’ list (see screenshot below). Sometimes, though, you can’t see the existing password. Instead, you should directly change it (current password is not required to perform this action).
8. Click on View/Change password to view or update the current password. Copy it.
9. Paste the user pass together with the rest of the database credentials into wp-config.php
10. Save the file. If you’ve been editing it locally, upload it to the server again.

NB! When migrating your site to a new host, a part of the process is creating a new database (not applicable to automatic migrations via WHM) and importing the contents of the old one into the new database. This implies that the name or at least the prefix of the database name changes. Remember to change it in wp-config.php file accordingly. The database gets in such cases also a new user. You are only free to reuse your old password, if you want.

If misspelling was the cause of the Error establishing a database connection issue, it should be resolved now.

Misspelled Site URL and Home

Another very common database-connected issue, which can result in Error establishing a database connection notification or 500 external server error is misspelling the site URL (the WordPress location) and/or the home URL (the URL, which your site is publicly accessible on) in your site’s settings.

You set the site URL and the Home values from within WordPress for existing sites and you can also always do it from within the database. Here’s how you do it:

1. Log into cPanel or another server control panel
2. Navigate to phpMyAdmin or to database management (usually through the Databases screen). Click on it.
3. Find and click on your WordPress database
4. In the list of tables, locate wp_options. Keep in mind that the table list is paginated! If you can’t find wp_options on the first page, navigate to the next one (navigation arrows are situated at the bottom of the table list).
5. Click on wp_options
6. To the right, you can see all entries for this table.
7. Locate siteurl and home 
8. Make sure that the siteurl points to the WordPress directory. The WordPress directory can in some cases differ from your home directory, if you decided to install WordPress in yoursite.com/wp or similar instead of under yoursite.com (this is a recommended setup for very heavy or trafficked sites only).
9. Make sure that home points to your site’s public URL. Check your spelling carefully and correct eventual errors. Use the correct protocol (http or https).
10. If you found an error, fix it and check, whether the the Error establishing a database connection notification is gone. It better be, as now we’ve reached the end of the list of issues fixable by you.

MySQL Server is Down

As long as you are still seeing the annoying Error establishing a database connection screen, chances are that the MySQL server is overloaded, malfunctioning or directly down. The MySQL server is the “home” of yours and others’ databases (on shared hosting). You don’t usually have admin rights or access to this server beyond phpMyAdmin. The only thing you can do, is to contact your hosting provider and inform them about the issue.