Fix 'Cannot connect to database' After MySQL 8.0 Migration

When does this error happen?

You've just migrated a WordPress site (or any PHP app) from an old server to a new one running MySQL 8.0. Everything looks good—files are copied, database imported, config updated. But the site throws: Cannot connect to database. No other clues. The database server is running, port is open, credentials look right. But it just won't connect.

Had a client last month who spent two days chasing this. Turned out to be a 5-minute fix once you know the cause.

Root cause: authentication plugin mismatch

MySQL 8.0 changed the default authentication plugin from mysql_native_password (used in MySQL 5.7 and earlier) to caching_sha2_password. When you dump and restore a database from an older MySQL version, the user accounts are restored with the old plugin setting. But MySQL 8.0 wants the new one. PHP's mysql_connect() and older PHP versions (like 7.2 or earlier) don't speak the new auth protocol. So the database server rejects the connection.

Another scenario: the user exists in the database but hasn't been granted privileges on the new server. The GRANT statements in your dump might not carry over correctly if you used --no-create-db or skipped the mysql system tables.

The fix: three numbered steps

Step 1: Check the current auth plugin for your user

Log into MySQL as root (or a superuser):

mysql -u root -p

Then run:

SELECT user, host, plugin FROM mysql.user WHERE user = 'yourdbuser';

If the output shows caching_sha2_password and your PHP version is below 7.4, that's your problem. If it shows mysql_native_password and you still can't connect, skip to Step 3.

Step 2: Change the auth plugin and reset the password

Run this command to switch to the old plugin and set a new password (replace yourdbuser, host, and yourpassword):

ALTER USER 'yourdbuser'@'host' IDENTIFIED WITH mysql_native_password BY 'yourpassword';

For example, if your user is wordpress connecting from localhost:

ALTER USER 'wordpress'@'localhost' IDENTIFIED WITH mysql_native_password BY 'S3cur3P@ss!';

Then apply the changes:

FLUSH PRIVILEGES;

Step 3: Grant proper privileges (if needed)

If the user exists but still can't connect, they might lack privileges on the specific database. Run:

GRANT ALL PRIVILEGES ON yourdb.* TO 'yourdbuser'@'host';
FLUSH PRIVILEGES;

Replace yourdb with your actual database name. For a WordPress site, that's usually the database name from wp-config.php.

What to check if it still fails

Host value mismatch: Your wp-config.php uses localhost but the MySQL user is defined as 'user'@'127.0.0.1' or vice versa. Check the host column in Step 1. They must match exactly.
PHP version too old: PHP 5.6 or 7.0 doesn't support caching_sha2_password at all. You need PHP 7.1+ with the mysqlnd driver, or stick with mysql_native_password (Step 2).
Firewall or bind address: If the database is on a separate server, ensure port 3306 is open and MySQL is listening on 0.0.0.0 (check bind-address in /etc/mysql/my.cnf).
Password contains special characters: If your password has $, !, or #, try wrapping it in single quotes in the ALTER USER command. Or just reset it to something simpler for testing.
Used a different dump method: If you used mysqldump --all-databases, check whether the mysql system tables were restored properly. Sometimes they get corrupted. Recreate the user manually instead.

That's it. In nine out of ten cases, Step 2 alone fixes it. Don't waste time reinstalling MySQL or hunting for config typos—just check that auth plugin.