WordPress requires reasonable resources to run with high traffic. Sign up to BitLaunch today for a fast cryptocurrency vps.

Though it was once a simple blogging platform, WordPress has grown into a fully fledged content management system and website builder. The ability to combine its underlying framework with a variety of open-source plugins has led to widespread adoption and utilization by some of the biggest companies in the world.

Unfortunately, though, that simplicity comes with some downsides. When WordPress does throw up an error, it doesn't give much technical detail, and as a result it can be difficult to debug. No issue is a better example than the dreaded "Error establishing Database Connection".

Thankfully, WordPress database errors  usually caused by one of three things. On a fresh install, it's likely that the database login credentials in your wp-config file don't match a MySQL database on your server. If you suddenly experience it after a period of high traffic, it could be that the server has run out of memory and your database has crashed. Finally, and more seriously, you can run into this issue if the database tables have been damaged after you've made some kind of change.

In this tutorial we're going to run through some basic troubleshooting steps for these common scenarios. We're going to assume you're hosting your WordPress site on a VPS with full access. If you aren't, it's likely better to contact your web host support than troubleshoot yourself. If you're struggling to install the CMS correctly on BitLaunch, we recommend BitLaunch's one-click setup or our tutorial for CentOS.

That said, let's start with the first scenario:

Check your WordPress configuration

In some cases, you can fix the "WordPress error: trouble establishing a database connection" message with just a couple of config tweaks. Your wp-config.php will be located in the root directory of your site. In most cases, that'll be in /var/www/public_html, but it could be under the domain name if you have a multi-site setup.

If you're still stuck you can use the knowledge gained from our find command tutorial:

sudo find / -name "wp-config.php"

Then type the following, replacing the directory with yours:

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

At the top of your config file you'll see the comment /** The name of the database for WordPress */ followed by this:

define('DB_NAME', 'database_name');

/** MySQL database username */
define('DB_USER', 'database_username');

/** MySQL database password */
define('DB_PASSWORD', 'database_password');

You'll want to note known the information after the comma next to DB_NAME, DB_USER, and DB_PASSWORD. Make sure they're all in single quotes and have the parenthesis and semi-colon intact. Then, check your MySQL database to make sure it matches. Log in with:

mysql -uroot -p

If Linux tells you MySQL isn't running, it's probably crashed. Skip to the next heading in this tutorial. Otherwise, once you're logged in, type:

SHOW DATABASES;

If you forgot the semi-colon at the end of DATABASES, you're not alone. Type exit; if you get stuck. The database list will look something like this if you run it correctly:

+--------------------+
| Database           |
+--------------------+
| wordpress          |
| information_schema |
| mysql              |
| performance_schema |
| bitlaunch          |
| sys                |          
+--------------------+

Make sure your database name matches the one in your wp-config. If it does, check the database user instead:

select user from mysql.user;
+------------------+
| user             |
+------------------+
| admin            |
| debian-sys-maint |
| mysql.infoschema |
| mysql.session    |
| mysql.sys        |
| root             |             
| wordpress        |
+------------------+
Output

You can't retrieve your MySQL password to check it, but you can change it to a password of your choice. Type:

ALTER USER 'username'@'localhost' IDENTIFIED BY 'newpass';
FLUSH PRIVILEGES;

Plug all of the above details back into your wp-config file with sudo nano /var/www/public_html/wp-config.php. Save it with Ctrl + O and then press Ctrl + X to exit. Visit your site to check if everything is working again.

Check if MySQL has run out of memory

If visit your website to a seemingly random "error establishing database" message, there's a good chance your database has just crashed due to lack of resources. It's possible your server specs aren't high enough, but this can also happen in isolated instances.

The first step is to check that MySQL is running. There are a few ways of doing this, but first we'll check its uptime with MySQL itself:

mysqladmin -u root -p status

If MySQL is running, you'll see something like this:

Uptime: 1822314  Threads: 2  Questions: 392010  Slow queries: 0  Opens: 909  Flush tables: 3  Open tables: 831  Queries per second avg: 0.215

If it's not, you'll get the following error:

sysqladmin: connect to server at 'localhost' failed
error: 'Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)'
Check that mysqld is running and that the socket: '/var/run/mysqld/mysqld.sock' exists!
Output

We can also check if the MySQL service is running via systemctl:

systemctl status mysql.service

If it's running you'll get the following output:

● mysql.service - MySQL Community Server
     Loaded: loaded (/lib/systemd/system/mysql.service; enabled; vendor preset: enabled)
     Active: active (running) since Sat 2020-11-21 08:30:25 UTC; 2min 57s ago
    Process: 553156 ExecStartPre=/usr/share/mysql/mysql-systemd-start pre (code=exited, status=0>
   Main PID: 553174 (mysqld)
     Status: "Server is operational"
      Tasks: 37 (limit: 1137)
     Memory: 393.0M
     CGroup: /system.slice/mysql.service
             └─553174 /usr/sbin/mysqld

Otherwise, you'll see this:

● mysql.service - MySQL Community Server
     Loaded: loaded (/lib/systemd/system/mysql.service; enabled; vendor preset: enabled)
     Active: inactive (dead) since Sat 2020-11-21 08:34:39 UTC; 3s ago
    Process: 55315 ExecStartPre=/usr/share/mysql/mysql-systemd-start pre (code=exited, status=0>
    Process: 553174 ExecStart=/usr/sbin/mysqld (code=exited, status=0/SUCCESS)
   Main PID: 553174 (code=exited, status=0/SUCCESS)
     Status: "Server shutdown complete"

You can start MySQL again by typing:

sudo systemctl start mysql

Now we should check if this is a one-off instance or whether we need to upgrade our server. We can use zgrep to search our log files for "allocate memory" errors:

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

If your server crashed due to memory limitations, you'll see an output like this:

2020-11-21T09:52:12.604644Z 0 [ERROR] InnoDB: Cannot allocate memory for the buffer pool

If this only occurs once, you may have just seen a sudden surge in traffic or resource use elsewhere in the server. If there are several instances, you should really upgrade your server specifications.

Repair your WordPress Database

If your WordPress site is down after the above steps, your database could, unfortunately, be corrupt. There are a lot of moving parts in a WordPress site, and a faulty plugin install, incompatibility, or WordPress update can cause issue. This why you should always back up your database via your control panel or mysqldump before maintenance.

Thankfully, not all is lost if you didn't do that. If you don't have a backup you can try to repair your database using WordPress' in-built tool. To use the WordPress repair tool, though, we need to add a line to our wp-config.php.

Note that you should disable this as soon as you're done with repairs, as it poses a major security risk. Type:

sudo nano /var/www/html/wp-config

Paste this into the document and press Ctrl+O and Ctrl+X:

define('WP_ALLOW_REPAIR', true);

Now, in the web browser on your local PC, visit http://www.yoursite.com/wp-admin/maint/repair.php

If you have an SSL certificate naturaly replace the above with https://.... Click Repair Database and follow the on-screen instructions.

WordPress will check your database and give you an output like this:

The wp_users table is okay.
The wp_usermeta table is okay.
The wp_posts table is okay.
The wp_comments table is okay.

If you notice it making any repairs, try accessing your website again. If it doesn't detect any issues, your best bet may be to restore the database from a backup if you can. If it still doesn't work, your issue is probably a less common one. You may want to contact support or trawl fo