Troubleshoot a MySQL connection

Start with the exact error. Verify that MySQL is running, the host and port are reachable, and the account matches the connection origin.

Treat the connection as layers and stop at the first layer that fails.

First, verify the inputs. Print the resolved host, port, database name, and username, but never the password. localhost may use a Unix socket while 127.0.0.1 uses TCP, so test the same transport as the application.

Next, prove that the server is reachable:

mysqladmin -h db.example.com -P 3306 ping

A timeout points toward DNS, routing, firewall rules, a provider allowlist, or a server that is not listening. An immediate authentication error proves that the network path worked and moves the investigation to credentials or grants.

Connect with the command-line client using the same host, port, account, database, and TLS expectations:

mysql -h db.example.com -P 3306 -u app_user -p app_database

If this works while the application fails, compare driver settings, environment loading, connection-string escaping, and certificate configuration. If it fails, inspect the server-side account and grants with an administrative connection:

SHOW GRANTS FOR 'app_user'@'application-host';

MySQL accounts include both a user and a host. 'app_user'@'localhost' and 'app_user'@'%' are different accounts, so a correct password can still produce “access denied” from a different origin. Once connected, confirm the selected database with SELECT DATABASE(); and test the smallest failing query. A successful login does not imply permission to read every table.

TLS failures are another distinct layer. Check whether the server requires encryption, whether the client trusts the certificate authority, and whether the hostname matches the certificate. Do not disable certificate verification as the permanent fix.

Changing every setting at once destroys the evidence that tells you which layer failed.

Try it: take one real connection error and write down which layer it proves succeeded. For example, “access denied” means DNS, TCP reachability, and a responding MySQL server already worked.