Search guides

Fix a database that will not connect

We'll check the service is running, the port is listening, credentials and firewall, and test with mysql or psql—or tell you when to escalate.

Troubleshooting · Databases
15–30 min
What you'll need
  • Console or SSH access to the database server
  • sudo on the server
  • Client credentials (username, password)
Step 1 of 7

Quick triage — pick your path

Get started

Choose the option that matches what you see. You can jump straight to that section.

Show full guide

Steps

Goal: Check the database service, port, credentials, and firewall.

  • Run systemctl status mysql or systemctl status postgresql to confirm the service is running.
  • Good: Service is active. Proceed to Check service and port.
  • Bad: Service inactive—start it or see fix-linux-server-will-not-start-service.

Check service and port

Goal: Confirm the database is running and listening on the correct port.

  • Run netstat -tlnp | grep 3306 (MySQL) or netstat -tlnp | grep 5432 (PostgreSQL). Or ss -tlnp.
  • MySQL uses 3306, PostgreSQL uses 5432.
  • Good: Port is in LISTEN state. Proceed to Test locally.
  • Bad: Port not listening—check bind-address (MySQL) or listen_addresses (PostgreSQL).

Test locally

Goal: Verify the database accepts connections from the server.

  • MySQL: run mysql -u root -p (or your user).
  • PostgreSQL: run psql -U postgres -h localhost (or your user).
  • Good: You get a prompt. The issue is firewall or client config. Proceed to Check firewall.
  • Bad: Connection refused or auth failed—check credentials, pg_hba.conf, or MySQL grants.

Check firewall

Goal: Confirm the database port is open for remote clients.

  • Add rule: ufw allow 3306/tcp (or 5432) and ufw reload, or firewall-cmd --add-port=3306/tcp --permanent and firewall-cmd --reload.
  • From the client: nc -zv host 3306 (or 5432) to test reachability.
  • Good: Port is reachable. Check client host, port, and credentials.
  • Bad: Firewall blocks—add the rule and reload.

When to escalate

Escalate if:

  • The service will not start (see fix-linux-server-will-not-start-service).
  • You cannot access the server console.
  • The fix requires security policy or config management changes.

Provide systemctl status, netstat/ss output, and the exact connection error.

Verification

  • mysql -u root -p or psql -U postgres -h localhost connects from the server.
  • netstat -tlnp or ss -tlnp shows the database port in LISTEN state.
  • The client connects with the correct host, port, and credentials.

Escalation ladder

Work from the device outward. Stop when the problem is fixed.

  1. Service status systemctl status mysql or postgresql.
  2. Port listening netstat -tlnp or ss -tlnp | grep 3306 or 5432.
  3. Test locally mysql -u root -p or psql -U postgres -h localhost.
  4. Firewall and credentials ufw/firewall-cmd; check host, port, user, password.
  5. Escalate Provide systemctl status, netstat/ss, and connection error.

What to capture if you need help

Before calling support or posting for help, have these ready. It speeds everything up.

  • systemctl status mysql or postgresql
  • netstat -tlnp or ss -tlnp output
  • Exact connection error from client
  • Steps already tried

Is the database service running?

systemctl status mysql or postgresql.

Run `systemctl status mysql` or `systemctl status postgresql`. Inactive: start the service. Active: check port with netstat or ss. Good: service running. Bad: service will not start—see fix-linux-server-will-not-start-service.

Yes No

You can change your answer later.

Start the service

Run `sudo systemctl start mysql` or `sudo systemctl start postgresql`. If it fails, check logs: journalctl -u mysql or journalctl -u postgresql. Escalate if the service will not start.

Done

Is the port listening?

netstat -tlnp | grep 3306 or 5432; ss -tlnp.

Run `netstat -tlnp | grep 3306` (MySQL) or `grep 5432` (PostgreSQL). Or `ss -tlnp`. Listening: test locally with mysql or psql. Not listening: check bind-address (MySQL) or listen_addresses (PostgreSQL). Good: port in LISTEN. Bad: not listening—check config.

Yes No

You can change your answer later.

Does mysql or psql connect locally?

mysql -u root -p or psql -U postgres -h localhost.

Run `mysql -u root -p` or `psql -U postgres -h localhost`. Connects: issue is firewall or remote config. Fails: check credentials, pg_hba.conf, or MySQL grants. Good: local works—check firewall and client config. Bad: credentials or server config.

Yes No

You can change your answer later.

Does the firewall allow the port?

ufw allow 3306/tcp or firewall-cmd --add-port=5432/tcp.

Add firewall rule: ufw allow 3306/tcp (or 5432) and reload, or firewall-cmd --add-port. From client: nc -zv host 3306. Good: port reachable—check client host, port, credentials. Bad: firewall blocks—add rule.

Done

Check credentials and server config

MySQL grants; PostgreSQL pg_hba.conf.

MySQL: SHOW GRANTS FOR user@host; add GRANT if needed. PostgreSQL: edit pg_hba.conf, add host line for client IP, reload. Confirm you should see the correct grants or rules.

Done

Check bind/listen config

MySQL: bind-address in mysqld.cnf—0.0.0.0 for remote. PostgreSQL: listen_addresses in postgresql.conf—* for all. Restart the service after change. Confirm you should see the port listening.

Done

Reviewed by Blackbox Atlas

Frequently asked questions

Why would a database not connect?
The service is stopped, the port is blocked by a firewall, the host or port is wrong, credentials are invalid, or the server is unreachable. Check systemctl status, netstat/ss, and test with mysql or psql.
Can I fix database connection issues myself?
Yes. Start the service, open the firewall port, verify host and credentials. Test with mysql -u or psql -U locally first.
When should I escalate database connection issues?
If the service will not start, you cannot access the server console, or the fix requires config or security policy changes. Provide systemctl status, netstat/ss output, and the exact error.

Rate this guide

Was this helpful?

Continue to