Error establishing a database connection

Why it happens

WordPress says this is usually caused by an error in wp-config.php: the database name, username, password or host is wrong. After a migration, check this first: the new host usually has its own database credentials and host name. Other documented causes are a database that has hit its quota and been shut down, or a database server that is down.

Where you see it, and what it affects

WordPress shows this message in place of the page when it cannot reach its database. It reads the database name, user, password and host from wp-config.php on every request, so the public site and the admin screens both fail while the connection is broken. After a move to a new host this is the first file to check, because the new host usually issues its own database credentials and host name. A database over its quota, or a database server that is down, causes the same message.

How to fix it

1. 1

   Step 1

   Open wp-config.php on the new server and check the database name, user, password and host against the values in your hosting control panel.

2. 2

   Step 2

   Confirm the database was actually imported and the user has permissions on it.

3. 3

   Step 3

   If the settings are right, ask the host whether the database server is down or over quota.

4. 4

   Step 4

   If the config and host both check out, WordPress suggests scanning the site for compromise.

define( 'DB_NAME', 'database_name' );
define( 'DB_USER', 'database_user' );
define( 'DB_PASSWORD', 'database_password' );
define( 'DB_HOST', 'localhost' );

wp db check

Check that it is fixed

• From the site root on the server, run wp db check. WP-CLI connects with the DB_HOST, DB_NAME, DB_USER and DB_PASSWORD values in wp-config.php and should print Success: Database checked.
• Open the home page and /wp-admin in a private browser window. Both should load without the error.

Sources

Full guide: How to migrate a WordPress site to a new host without downtime →