Connection troubleshooting

Diagnose authentication, network, SSL, and SSH failures when QueryDeck cannot connect to a database.

For: PostgreSQL and MySQL connections that fail Test Connection or disconnect unexpectedly.

Start in the connection editor and click Test Connection. QueryDeck uses the same host, credentials, SSL settings, and SSH tunnel that normal queries use. A successful test shows a green checkmark and the server version. A failed test shows the connection error so you can fix the layer that failed.

1. Check host and port

Confirm that the hostname is the one your provider exposes to your Mac, not an internal hostname that only works inside a cloud network.

Default ports:

Database	Default port
PostgreSQL	`5432`
MySQL / MariaDB	`3306`

Managed providers sometimes expose a different proxy port. Use the value from the provider's connection string rather than assuming the default.

If the database is private and only reachable from a bastion or VPN, configure an SSH tunnel instead of pointing QueryDeck directly at the private address.

2. Check username, password, and database name

Authentication failures usually mean one of these fields is wrong:

username;
password;
database name;
provider-specific connection user or branch name.

If you pasted a URI, make sure special characters in the password are URL-encoded. If qdeck discovered the connection from a project, run the CLI diagnostic flow described in CLI troubleshooting to see which config and environment were selected; passwords are redacted from the summary.

3. Match the provider's SSL requirement

Most managed PostgreSQL and MySQL providers require SSL.

Typical starting points:

PostgreSQL cloud database: require;
MySQL cloud database: REQUIRED;
organization-managed CA: verify-full, VERIFY_CA, or VERIFY_IDENTITY depending on the engine and policy.

If you see a certificate, CA, hostname, or TLS error, use the dedicated SSL/TLS modes guide. It covers custom CA files, certificates from the macOS Keychain, client certificates, and SSL through an SSH tunnel.

4. Separate SSH errors from database errors

When SSH tunneling is enabled, two connections have to succeed:

QueryDeck ──SSH──> bastion ──TCP/SSL──> database

If the bastion itself refuses the connection, verify its SSH host, port, user, and authentication method. The SSH tunnels guide includes checks for:

connection refused on the bastion;
rejected SSH keys;
host-key changes;
a database host that is unreachable from the bastion.

If SSH succeeds but the database connection fails, troubleshoot the database host/port/SSL settings from the bastion's point of view.

5. Use the provider's external connection string

Several providers expose more than one endpoint. From your Mac you generally need the public/external endpoint unless you are connected to the provider's private network.

Provider-specific notes are available for:

PostgreSQL — Supabase, Neon, Railway, Render, RDS, DigitalOcean;
MySQL — PlanetScale, RDS, DigitalOcean, self-hosted MySQL/MariaDB.

Connection drops after it was working

For SSH connections, QueryDeck attempts one reconnect if the tunnel drops. If that reconnect fails, the connection icon turns red and QueryDeck shows a connection-lost notification. Reopen the connection after the network or bastion is reachable again.

For direct connections, re-run Test Connection first. A changed VPN, expired cloud endpoint, rotated password, or provider SSL requirement will usually surface there.