Tutorial

How To Debug the WordPress "Error Establishing Database Connection"

Published on April 21, 2017
How To Debug the WordPress "Error Establishing Database Connection"

Introduction

WordPress is one of the most popular open source content management systems in the world. Although it started out focused on blogging, over the years it has developed into a more flexible platform for websites in general. After almost fifteen years of development it is quite polished and robust, yet issues can still come up.

If you’ve recently attempted to load your WordPress-powered website and instead saw a message stating “Error Establishing Database Connection”, the cause is most often one of the following:

  • The database has crashed, often due to the server running out of memory
  • The database login credentials are incorrect in your WordPress configuration
  • The WordPress database tables have been damaged

Let’s walk through these issues one at a time to determine if they affect you, and how to fix them.

Prerequisites

This tutorial assumes the following:

  • You’re running WordPress on a machine that you have command line and sudo access to
  • Your database is running on the same server as WordPress (typical of a self-hosted WordPress setup, less typical of a shared WordPress hosting environment)
  • You know your database username, password, and the name of the database created for WordPress. This information should have been created during initial setup of your WordPress install.

Step 1 — Check the Server Memory Resources

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:

  1. 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.

Note: If you’re sure you have your connection details correct but you’re still having trouble logging in, it could be that your server is out of memory or under very heavy load. This could be due to a sudden burst of traffic to your website, and would explain the WordPress error. You may need to restart your server before you’ll be able to log in.

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

  1. 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

If your output is similar, we know MySQL is running and listening for connections. If you don’t see MySQL listed, try starting MySQL manually. On most systems that would look like this:

  1. sudo systemctl start mysql

Some Linux distributions (CentOS, notably) use mysqld instead of plain mysql for the service name. Substitute as appropriate.

MySQL should start. To verify, rerun the netstat command we used above, and check the output for a mysqld process.

MySQL and WordPress both need a good amount of memory to run properly. If MySQL has quit due to a low memory situation, we should see evidence of that in its error logs. Let’s look:

  1. zgrep -a "allocate memory" /var/log/mysql/error.log*

zgrep will search through log files, including older log files that have been archived as compressed .tar.gz files. We’re searching for lines that contain allocate memory, in any error.log* file in the /var/log/mysql/ directory.

Output
2017-04-11T17:38:22.604644Z 0 [ERROR] InnoDB: Cannot allocate memory for the buffer pool

If you see one or more lines like the above, your MySQL server ran out of memory and quit. If it’s just one line, you may be temporarily experiencing unusual traffic. If there are many error lines, your server is regularly becoming memory constrained. Either way, the solution is to migrate to a server with more available memory. On most cloud providers it’s a simple matter to upgrade an existing server with minimal downtime.

If you see no output after running the zgrep command, your server is not running out of memory. If your site is still serving errors, continue on to the next step where we’ll look at our WordPress configuration and make sure the MySQL login details are correct.

Step 2 — Check Database Login Credentials

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

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

  1. 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:

  1. 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:

wp-config.php
/** 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). Even if the login information looked correct, it’s worth attempting to connect to the database from the command line, just to make sure. Copy and paste the details right from the config file into the following command:

  1. mysqlshow -u database_username -p

You’ll be prompted for a password. Paste it in and press ENTER. If you get an Access denied error, your username or password are incorrect. Otherwise the mysqlshow command will show all the databases the specified user has access to:

Output
+--------------------+ | Databases | +--------------------+ | information_schema | | database_name | +--------------------+

Verify that one of the databases exactly matches what’s in your WordPress configuration file. If it does, you’ve verified that your config is correct and that WordPress should be able to log into the database successfully. Reload your website to see if the error is gone.

Still not working? The next thing to try is repairing the database.

Step 3 — Repairing the WordPress Database

Sometimes, due to a failed upgrade, a database crash, or a faulty plugin, your WordPress database can become corrupted. This problem can present itself as a database connection error, so if your problem wasn’t the MySQL server or the configuration file, try repairing your database.

WordPress provides a built-in utility to repair the database. It is disabled by default, because it has no access controls and could be a security issue. We will enable the feature, run the repairs, and then disable it.

Open up the wp-config.php file again:

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

On any blank line, paste in the following:

wp-config.php
define('WP_ALLOW_REPAIR', true);

This defines a variable that WordPress looks for when determining if it should enable the repair feature.

Save and close the file. Switch over to your browser and load the following address, being sure to substitute your site’s domain or IP address for the highlighted portion:

http://www.example.com/wp-admin/maint/repair.php

A database repair page will load:

WordPress database repair page

Press the Repair Database button, and you’ll be taken to a results page where you can see the checks and repairs happening in real-time:

WordPress database repair results page

Once the process finishes, be sure to open up the wp-config.php file again, and remove the line we just pasted in.

Did you notice any repairs being made? Try your site again, and check whether the error is gone. If unrepairable issues were found, you might need to restore the database from a backup if you have one available. Please reference our tutorial How To Import and Export Databases in MySQL for details on how to do so.

If no issues were found with the database, then we’ve still not discovered the problem. It could be intermittent issues we’re just missing, or something more obscure. Lets wrap up with a few other possibilities to try.

Conclusion

The majority of “Error Establishing Database Connection” problems should have been solved with the three steps above. Still, there could be more elusive issues that continue to present themselves in this way. Here are some more articles that might be useful in tracking down and neutralizing the cause of this error:

  • A frequent source of high traffic (and thus poor performance and errors) is a brute-force attack common to WordPress installs. You can neutralize the attack by following How To Protect WordPress from XML-RPC Attacks.
  • You may save some server resources by implementing caching on your WordPress install. There are many simple caching plugins out there for WordPress. Our tutorial, How To Configure Redis Caching to Speed Up WordPress will show you how to configure a particularly performant Redis-backed cache.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about us


About the authors

Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
 
10 Comments


This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

it happens to me several times. I never encountered this problem on other cloud.

It won’t let me log in, I get permission denied, please try again, can anybody help me

On the primary URL of my WordPress site, I’m only seeing an index of the files. At the bottom, its says:

Apache/2.4.52 (Ubuntu) Server at [domain] Port 443

User Sergiu Dumitriu on Stack Overflow suggested that a user with a similar (but intermittently problematic) situation ensure the if the default port for MySQL is different than the default 3306 to change it in wp-config.php. I have not had a chance to test this, but I don’t believe 443 corresponds to the MySQL port.

At /wp-admin, I see the following message:

Cannot select database

The database server could be connected to (which means your username and password is okay) but the [database-name] database could not be selected.

  • Are you sure it exists?
  • Does the [database-user] have permission to use the [database-name] database?
  • On some systems the name of your database is prefixed with your username, so it would be like [database-user]_[database-name]. Could that be the problem?

I have verified all of these scenarios are not the culprit by following this DigitalOcean guide. I get the titular “Error establishing database connection” when I attempt to repair the database as outlined in Repairing the WordPress Database.

User DriftingBlueCoral suggested repairing the MySQL tables with the command:

/usr/bin/mysqlcheck --all-databases --auto-repair

I attempted to run this, but received the following error:

 Access denied for user 'root'@'localhost' (using password: NO) when trying to connect

I’m not very familiar with Apache and MySQL, so I’m not sure how I can both run this command and use my root user’s password, since that would mean logging into MySQL and relying on MySQL commands.

It’s worth noting how I got here

My personal portfolio and this WordPress site are siblings on my server. I was uploading files via FTP and accidentally deleted the entire folder for my WordPress site. I attempted to cancel the process, but it had already wiped crucial files for the operation of the site.

I did not perform routine backups. I will now be performing routine backups.

Following DigitalOcean’s How To Install WordPress on Ubuntu 20.04 with a LAMP Stack that got me up and running the first time, I’ve arrived here. I’m confident the issue some kind of misalignment with my tables.

For instance, would the original database and user have been deleted with WordPress files? Again, I’m new to MySQL, but I don’t believe that is how it’s structured. Are the original database and user conflicting with the ones I have created following the guide? I feel like this is where my problem lies, but I simply am not sure, and am hopeful the community can lend me a hand.

Thanks.

If you’re like me and get stuck, the first thing you should do is try to add memory swap space - see tutorial at https://www.digitalocean.com/community/tutorials/how-to-add-swap-space-on-ubuntu-18-04

This comment has been deleted

    not a single thing is working for me I am getting the same problem and the commands you show here are not working for me “sudo: netstat not found” “mysql not found” what do i do please help me

    For me it was fixing crashed tables that did the trick (repair.php mentioned in the article did not help with the problem):

    /usr/bin/mysqlcheck --all-databases --auto-repair
    

    I’m stuck here:

    You’ll be prompted for a password. Paste it in and press ENTER. If you get an Access denied error, your username or password are incorrect.

    why are you giving access denied? I did exactly what the tutorial asks. I got Database name, username and password from my website’s wp-config file …

    how to fix this?

    Great article! I ran into an out of memory condition that caused the database error. A Power Cycle of the droplet fixed it.

    This was immensely helpful! Thank you.

    Try DigitalOcean for free

    Click below to sign up and get $200 of credit to try our products over 60 days!

    Sign up

    Join the Tech Talk
    Success! Thank you! Please check your email for further details.

    Please complete your information!

    Get our biweekly newsletter

    Sign up for Infrastructure as a Newsletter.

    Hollie's Hub for Good

    Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

    Become a contributor

    Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

    Welcome to the developer cloud

    DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

    Learn more
    DigitalOcean Cloud Control Panel