Error Establishing Database connection WordPress
Error establishing database connection when using WordPress, can be encountered if your WordPress based site can’t connect to the database used by your site. WordPress’ own advice about this is quite minimal, as it’s not really a WordPress centric issue, it’s more related to the underlying services (specifically the database) and how your WordPress is configured to connect to them.
If you’ve reached this page because you’ve just accidentally broken a site, and you need to get it up and running quickly, you might give the “quick and dirty just fix it guide” at the bottom of this page a try. You’ll need an understanding of how to use the tools in cPanel to be able to use this.
If you’ve got a bit more time on your hands, or are new to this kind of thing, I’d suggest working your way through this guide, as it’s more concise in instruction and you’ll learn more.
What the “Error Establishing Database Connection” problem looks like.
The database is integral to your WordPress site. It contains all variable information such as administrator usernames and passwords, page content, and even your site’s address. If the database can’t be connected to, or read, you’ve effectively go no site.
This guide covers the common fixes. This guide is specific to using a cPanel hosting account. If you’re using a different type of hosting you’ll need to locate and use the equivalent functions described in this guide.
You’re also going to need access to your hosting account where your site is held (you won’t be able to fix this issue without it).
Firstly, let’s cover what you’ll see if you have this issue. It looks like this:
What this means is that WordPress can’t connect to the database your site uses, or it can connect, but it can’t read anything relevant in the database.
There are multiple causes to this error message, and consequently there’s not a universal fix to this issue.
Due to this you’ll need an understanding of what’s happening to be able to fix the issue, so I’l cover this first.
How WordPress connects to the database.
The file within WordPress that defines the connection to the database is the wp-config.php file. This instructs WordPress how to connect to the database, and what to read once it has. WordPress has to use MySQL or an equivalent to connect to a database. MySQL has it’s own authentication mechanism, so it’s own users (which have usernames), and these users are assigned to databases, with privileges set (that defines what they can and can’t do to the database).
This file is located in document_root/wp-config.php (document root could be could be public_html (cPanel), httpdocs (plesk), /var/www/html (vanilla default apache), or something custom if you’re using a multisite hosting account).
The wp-config.php file contains:
- The name of the database that should be connected to: define( ‘DB_NAME’, ‘some_db_name’ );
- The database user that should be used when connecting to the database: define( ‘DB_USER’, ‘some_db_user’ );
- The database user’s password: define( ‘DB_PASSWORD’, ‘some_db_user’s_password’ );
- The location of the database server: define( ‘DB_HOST’, ‘some_db_server’ );
- The prefix of the tables in the database: $table_prefix = ‘someletters_’;
Obviously I’ve used some examples here (you’re not actually going to have a database called some_db_name or a user called some_db_user and so on), but you do need to know that this tells WordPress (in the same order as the above):
- Which database to connect to
- The user to be used when connecting to the database
- The password for the user connecting to the database
- The location of the database
- Which tables to read according to the $table_prefix value
When a page (any page, including the wp-admin area) is accessed, WordPress uses what’s in the wp-config.php file to establish a database connection and read the database.
When WordPress’ PHP is invoked (when a page is accessed) the wp-config.php file is read, and WordPress uses the information in this file to connect to the database. If it was humanised it would be something like:
WordPress: [reads DB_HOST and DB_NAME from wp-config.php] “Hey, localhost MySQL, can I connect to this database?”
MySQL: “What user are you connecting as?”
Wordpres: [reads DB_USER from wp-config.php] “This user”
MySQL: “What’s the password?”
WordPress: [reads DB_PASSWORD from wp-config.php] “It’s this”
MySQL: “OK, here you go”
WordPress: “Right, I need tables that start with [whatever $table_prefix is in wp-config.php]”
WordPress then reads the database content, executes it PHP, kind of combines the two, and generates page output.
If ANY of the above is incorrect, or if the database or database user defined in the wp-config.php file don’t exist, it will cause the error, as the net result of the above won’t be “OK, here you go”, it will instead be “No” and that’s when you see “Error establishing database connection”.
Causes.
Any of the following can cause the “Error establishing database connection” message in WordPress:
- The incorrect table prefix is defined in the wp-config.php file.
- Incorrect database is defined in the wp-config.php file.
- Incorrect database user is defined in the wp-config.php file.
- Incorrect database user’s password is defined in the wp-config.php file.
- The incorrect database host it defined in the wp-config.php file.
- The user in the wp-config.php file doesn’t have the correct privileges.
- The user in the wp-config.php file isn’t assigned to the database.
- The database defined in the wp-config.php file doesn’t exist
- The user defined in the wp-config.php file doesn’t exist
- The database has crashed or become corrupted.
- MySQL (or equivalent) isn’t running.
The issue you have could be one or more than one of the above.
Where to start your investigation.
The most prudent place to start is to look at what WordPress is going to try and use to connect to the database, then check that what it’s using does actually exist. If at any point you’re working through the steps below and you find WordPress is trying to use something that isn’t present you’d be best to check the things are missing section further down this page.
You can check what WordPress will try and use to connect by opening or editing the wp-config.php file in the cPanel file manager.
If you just have a single site cPanel account by default the wp-config.php file will be in the public_html directory, as your site exists in public_html. It is possible it could be elsewhere if you’ve manually modified your wordpress installation, or if you have a multisite type hosting account.
Use the cPanel file manager to locate the wp-config.php file, then right click on it and select “edit” and you’ll see this:
What this means is:
define( ‘DB_NAME’, ‘name_of_db’ ); = WordPress will try and connect to a database called name_of_db.
define( ‘DB_USER’, ‘name_of_db_user’ ); = WordPress will try and connect to the database as the name_of_db_user database user.
define( ‘DB_PASSWORD’, ‘password_of_db_user’ ); = That when WordPress tries to connect as name_of_db_user it will use password_of_db_user to authenticate as name_of_db_user.
define( ‘DB_HOST’, ‘localhost’ ); = That WordPress will try and connect to a database server that runs on the same server as your hosting account and site.
There is also a line a bit further down that looks like this:
$table_prefix = ‘wp_’;
What this means is that after connecting to the database, WordPress will try and read tables in the database that start with wp_ .
Checking what wordpress is going to try and use currently exists.
Now you know what WordPress will try to use when connecting to the database, the next step is to check that it all exists.
You’ll use two facilities in cPanel to do this:
- The MySQL Databases section of cPanel (this is used add and remove databases and database users, assign users to databases, rest their passwords, and check / repair databases).
- PHPMyAdmin (this is used to read and modify the content of databases).
Firstly, click on the “MySQL Databases” icon in your cPanel:
Then scroll down to the “Current Databases” section.
What you’re looking for here is the name of the database WordPress is trying to use (from the DB_NAME section of the wp-config.php file) and the database user WordPress is trying to use (from the DB_USER section of the wp-config.php file). You should see something like this:
What this tells us is:
In the Database column: That a database called name_of_db exists.
In the Size column: That the database is 3.25MB in size (so the database contains data).
In the Privileged Users column: That a user called name_of_db_user is assigned to the name_of_db database.
This should match the respective parts of your site’s wp-config.php file:
If you’re seeing what I’ve outlined above, that’s a good start. You’ve validated that the database WordPress is going to try and use is present and contains some data, and that the database user WordPress is going to try and use is present.
If either the database or the database user defined in the wp-config.php file aren’t present in the “Current Databases” section of cPanel, this will be a problem, as WordPress is trying to either connect to a database that doesn’t exist, or connect using a database user that doesn’t exist. You can expect this to fail.
Provided both the database or the database user defined in the wp-config.php file are present, we’re going to carry out some more checks on the MySQL Databases page of cPanel, to address the following.
The user in the wp-config.php file doesn’t have the correct privileges.
On the MySQL Databases page of cPanel, in the “Current Databases” section, click on the user that WordPress is trying to use:
You’ll then see a page showing the privileges the user has when accessing the database.
As this issue can be caused by the user having incorrect privileges, we’re going to give the user all privileges when connecting to the database.
To do this, click on “All Privileges” at the top, then click on “Make Changes” at the bottom. This gives the user assigned to the database the ability to do anything to the database:
Now return back to the MySQL Database page, as there are some more checks we need to undertake.
The database user’s password is incorrect.
If the password defined in the wp-config.php file isn’t the correct password for the database user this will cause the issue, as WordPress won’t be able to connect to a database if it’s using the wrong database user’s password.
The quick and easy way to sort this out, is to set the password found in the wp-config.php file as the password for the database user that’s defined in the wp-config.php file.
To do this, open the wp-config.php file using the cPanel file manager, then select and copy the password defined in the DB_PASSWORD section of the wp-config.php file:
- Open the cPanel file manager.
- Locate the wp-config.php file
- Right click on the wp-config.php file
- Click “edit”
- Select the password in the DB_PASSWORD section (make sure you don’t select either of the ‘ marks)
- Right click on the selected text
- Click copy
Like this:
Now you’ve got the password from the wp-config.php file on your computer’s clipboard, we’re going to set this as the database user’s password. To do this go back in to the MySQL Databases section of cPanel:
Then scroll down to the “Current Users” section, and on the same line as the database user (as seen in the wp-config.php file) click on “change password”:
Now paste the password in to BOTH the “Password” and “Password again” fields, then click “Change Password”:
If you’ve got this far and your WordPress is still showing the same error message, there’s another check you can carry out, still in the MySQL Database section of cPanel:
The database has crashed or become corrupted.
In the MySQL databases section of cPanel there’s a utility you can use to repair databases, which you’ll need to do if the database has crashed tables.
Then scroll down to the “Modify Databases” section, then:
- Select the database (as seen in the site’s wp-config.php file) on the same line as “Repair Database”
- Click “Repair Database”
Like this:
If you’ve got this far and your WordPress is still showing the error message, there’s another check you can carry out, but this time, we’ll us PHPMyAdmin to carry out this check.
MySQL (or equivalent) isn’t Running.
You can’t actually fix this yourself. You’ll need to contact your hosting provider if this is causing the problem you face. You’ll also have had problems carrying out the above if MySQL isn’t running (you can’t change a database user’s password or repair a database without MySQL running.
On the main cPanel page, click on the PHPMyAdmin icon:
if MySQL is running you’ll see this:
If you don’t see a page that looks like the above, and instead see a lot of red lines instead, MySQL isn’t accessible and most likely not running. You can’t fix this yourself, you’ll need to contact your hosting provider (although they will most likely be aware of the issue and working on it).
While you have PHPMyAdmin open there’s another check you can undertake.
DB_HOST in wp-config.php is incorrect.
PHPMyAdmin can be used to establish “where” the database server is that contains your site’s database.
In PHPMyAdmin look at the areas highlighted in the screen shot below:
The mention of the word “localhost” here means that the database server is running on the same server that you’re hosting account is held on. What you should have in your site’s wp-config.php file, in the DB_HOST section should match the “server” seen in PHPMyAdmin:
If the “server” seen in PHPMyAdmin is something other than localhost, you’ll need to set the DB_HOST in your wp-config.php file to the same as the server seen in PHPMyAdmin.
For example, if you see this in PHPMyAdmin:
Server: dbhost1.hosting.com via Unix socket
User: something@dbhost1.hosting.com
That means the DB_HOST in the site’s wp-config.php file should be set to the same, for example:
You’l need to save changes to wp-config.php if you make any.
What you’re doing here is telling WordPress “where” it should connect to, to be able to connect to the site’s database.
There’s one more check we can carry out in PHPMyAdmin.
Is $table_prefix correct?
You can use PHPMyAdmin to see what the table prefix is on your database tables..
Open PHPMyadmin, then click the + next to your cPanel username to expand (1 in the picture below).
Then click on the name of the database, as defined in your site’s wp-config.php file (2 in the picture below).
Then look at the beginning of a table name and you’ll see the prefix, which is the part before and including the underscore at the beginning of all tables (3 in the picture below).
In the example above, you can see that the tabel prefix is:
wpsk_
So this means, that for WordPress to be able to read the correct tables, the wp-config.php file of the corresponding site, should have this set:
You may need to update your site’s wp-config.php file to define the correct table prefix.
THINGS ARE MISSING!
If there’s something that’s defined in the wp-config.php file that doesn’t exist in your cPanel, WordPress is trying to connect to something that isn’t present. Obviously things can’t be connected to that don’t exist so that can also cause the error.
The database is missing.
The thing you REALLY don’t want to be missing is your site’s database.
If there are no databases listed in the “Current Databases” section of the MySQL Databases page in cPanel there aren’t any databases present. You’re either going to have to restore a backup of the database from within your cPanel (how you’d do this varies between hosting providers – you might consider seeking their assistance with restoring a backup) or, if you have a local back of the site’s database, create a new database, import your local backup, then assign a user to the database, and then configure your wp-config.php file with what you’ve just created. I’ll cover this below.
If there are databases or a database listed in the “Current Databases” section of the MySQL Databases page in cPanel it’s possible that what’s defined as the DB_NAME in the wp-config.php file is wrong. You’re then going to need to work out which of the databases that you can see as being present are the one your site uses, then configure your wp-config.php file to connect to the correct database.
You can use PHPMyAdmin to check this.
Open PHPMyadmin:
Then click the + next to your cPanel username, then click the + next to the name of a database:
This will show you all the tables in the database, and what we’re looking for is a table that has the word options in it (a prefix may well be in front of the word options like abc_options or wp_options:
The reason we’re looking for the options table is because this contains the site address, and it’s usually at the top of the table:
So if the address of the site you’re trying to fix is https://www.yourwebsiteaddress.com there’s a good chance that you’ve found your site’s database (I’ll come to the reason why I use the words “good chance” in a moment).
In the context of the above, the database we expanded was called name_of_db:
So for wordpress to connect to this database, the DB_NAME needs to be name_of_db like this:
The reason I used the phrase “there’s a good chance…” above is because this might not actually be the correct database. It could be an old one. It depends on what you’ve done in your account, and how tools you’ve used (to do things like create staging sites) might operate. Without being a mind reader or having a time machine, it’s quite hard to say exactly what’s happened here, but the good news is that as all your page content is held in your site’s database AND is timestamped, so you can check the posts table (which is where your page and post content is stored) as well as the options table to work out which database has the most recent content and the correct site address (respectively).
You’d access the posts table just like you did the options table (expand the cPanel user, expand a database, click on the posts table):
You should see something that looks like this (note the post_date and post_date_gmt column headings):
Click on the column heading post_date_gmt to sort by this column (you might need to click it a couple of times) until you see the most recent timestamp at the top. This is the most recent time page content was published. If this timestamp corresponds to the most recent time you updated any page content, then you’re most likely looking at the right database. If the timestamps aren’t recent and you’ve made more recent changes to page content, then you’re probably looking at an old copy of the database, so it would probably be a good idea to start checking other databases to see what’s in them.
You might need to do a bit of poking around to know which is the correct database to set in the wp-config.php file’s DB_NAME section. What you’re looking for is:
- A database that contains your site’s address in the options table
- The database that fulfils the above AND has to most recent timestamp on entries in the posts table
So just for example’s sake, let’s say that the database you found that fulfils the two points above has the name i_found_the_db this means you’d need to update the DB_NAME in your site’s wp-config.php file with i_found_the_db just like this:
The database is missing, but you have a backup.
Firstly, well done for being sensible and having a locally saved backup of your site’s database. That said, it’s going to need to be a .sql, gzip, bzip2, zip or an .sql.gz file for what I’m about to mention to work.
What you’ll need to do is:
- Create a new database
- Import your database back in to the newly created database
To do this in cPanel click on MySQL databases:
Then locate the “Create New Database” section.
Enter something in the highlighted field below (make a note of it), then click “Create Database”:
IMPORTANT: See the “word_” part? that’s actually part of the database name (by default in cPanel databases are prefixed by the cPanel username).
Consequently if you type:
my_new_db
in the field highlighted above, the database name will actually be:
word_my_new_db
So the DB_NAME part of the wp-config.php file would need to be this to connect to the newly created database (don’t do this yet, this is just so that you know):
define( ‘DB_NAME’, ‘word_my_new_db’ );
For now, you just need to make a note of the new database’s name.
Before you update the wp-config.php file, you need to import your backup using PHPMyAdmin, so go back to the main cPanel page, then click on PHPMyAdmin
Then click the + next to your cPanel username (in this example, my cPanel username is word):
Then click on the name of the database you just created:
Then up at the top, click on “Import”:
Then click on “Choose file” browse to and select your locally stored database backup, then click “import”:
You might have to set up a database user, and then assign the user to the database you’ve just created as well this is covered in the following section.
For now, update your site’s wp-config.php file with the database you’ve just created and imported to:
The database user is missing.
If you can’t see the database user that’s mentioned in the wp-config.php file in the “current users” section of the cPanel MySQL databases page, you’ll need to create one, the assign this user to the site’s database.
First, check what’s set in the DB_USER section of the wp-config.php file:
You’ll then need to look at the users in the “current users” section of the cPanel MySQL databases page, so go in to MySQL databases from the main cPanel page:
Then check the “Current Users” section at the bottom.
The user defined in the sites wp-config.php file doesn’t exist, so let’s create one. To do this scroll up the page until you see “Add new user” then in this section (make a note of all these as you go remembering to include the equivalent of word_ in the username):
- In the “Username” field enter a username.
- In the “Password” specify a password.
- In the “Password (Again)” field specify the same password as you did in step 2.
- Click “create user”
Then we need to assign the user that’s been created to the sites’s database. Sill in the MySQL Databases section of cPanel locate the “Add user to database” section, and:
- In the “User” drop down, select the user you’ve just created.
- In the “Database” drop down select your site’s database
- Click “Add”
If you then check the “Current Users” section you’ll then see the user you’ve just created:
Now you’ll need to assign the new user you’ve created to your site’s database. To do this locate the “Add user to database” section and in this section:
- In the user drop down select the database user you’ve created
- In the database drop down select your site’s database
- Click add
On the following page, tick “All Privileges” then click “Make Changes”:
Finally you need to update the wp-config.php file with:
DB_NAME = The name of the database used by your WordPress (if you haven’t done so already
DB_USER = The database user’s username you created above
DB_PASSWORD = The password of the database user you created above
Then save your changes.
A WORD OF WARNING.
If you’re copying and pasting database user’s usernames and database names directly from the cPanel interface in to the wp-config.php file, this can include formatting information that you can’t see. If this is present, you won’t be able to tell, and it makes what’s in the wp-config.php file incorrect, even though it looks right.
The best thing to do to avoid this is to copy and paste everything in to a plain text editor (notepad on a PC or Text Edit on mac, you need to make sure formatting is set to plain text in the latter) then copy and paste from the plain text editor to the wp-config.php file, as this will strip out any unwanted formatting information.
I’ll let you guess how I found that out.
My quick and dirty “just fix it!” guide.
You’ll need an understanding of how to use the facilities in your hosting account to be able to follow this, and where to find things as I’m not going to include any pictures. I’m writing this for those of you that have a handle on what’s going on, but don’t know how something’s been messed up. Say if you’d accidentally brought down your company’s website, and needed to get it back up and running quickly, before anyone noticed (not that I’ve ever done that, honest!) you might find this handy.
OK, so here goes:
- Open the wp-config.php file, make a note of what’s set as the DB_NAME value.
- Open PHPMyAdmin, locate the database you made a note of in step 1 and validate that it’s the database for the site, and that the posts table contains recent content if it does go to step 3, if the database isn’t present you’re going to have to stop reading this and start reading the things are missing section.
- Make a note of the DB_USER that’s set in the wp-config.php file. Take a copy of the password set in the DB_PASSWORD section of the wp-config.php file.
- Reassign the user you made a note of in step 3 to the database you made a note of in step 1 granting all privileges when doing so. If the user isn’t present skip to step 6.
- Change the password of the user defined as DB_USER in the wp-config.php file to the DB_PASSWORD you took a copy of in step 3. Obviously if the DB_USER doesn’t exist, you can’t carry out 4 and 5, so you’ll need to:
- Create a user with the same name as DB_USER that’s set in the wp-config.php, using the password you took a copy of in step 3.
- Assign the user created in step 6 to the database defined in the DB_NAME section of the wp-config.php file, granting all privileges when doing so.
Site still not working?
Check the $table_prefix defined in the wp-config.php file is actually the prefix of the tables in the database that contains your site’s content. Update the $table_prefix value defined in the wp-config.php to match the table prefixes (as seen in PHPMyAdmin).
If you see an old site, either you’ve configured wordpress to connect to an old database, OR you’ve configured it to connect to the right database, with the wrong table prefixes (it’s possible to have 2 sites in one databases with different table prefixes for each site).
In Conclusion.
- The “Error establishing database connection” message means that WordPress can’t connect to the database defined in the wp-config.php file.
- There are lots of different causes to this issue.
- Each cause has it’s own fix.
- You’ll have to identify the cause to apply the appropriate fix.
- Following the Quick and Dirty Just Fix it guide on this page covers the majority of fixes in quick succession.