SSL/TLS modes

For: developers.

Most managed databases require SSL. QueryDeck supports every mode libpq (PostgreSQL) and libmysqlclient (MySQL) expose, plus the ability to bring your own CA certificate.

PostgreSQL SSL modes

PostgreSQL uses the five standard libpq modes:

When to use which

What each mode does

• disable — Plain TCP. Never use this over a public network.
• allow — Try plain first, fall back to SSL if the server requires it. Rare and not recommended.
• prefer — Try SSL first, fall back to plain if the server refuses. Convenient for mixed environments but won't catch a server that silently downgraded to plain.
• require — Demand SSL but don't verify the certificate. Protects against passive eavesdropping. Does not protect against active man-in-the-middle attacks (because the cert isn't checked).
• verify-ca — Demand SSL and check that the server certificate is signed by a CA you trust. Doesn't check the hostname.
• verify-full — Demand SSL, check the CA, and verify the certificate's CN/SAN matches the hostname. The only mode that protects against active MITM.

For most cloud providers, require is what they hand you. They issue valid certificates but use intermediate CAs that don't ship with the system trust store. require works because it skips CA verification. If your security policy says verify, you'll need to download the provider's CA cert and switch to verify-full.

MySQL SSL modes

MySQL uses different names, but the meaning is similar:

The recommendations from the PostgreSQL section apply equally.

Bring your own CA

For verify-ca and verify-full modes, QueryDeck needs the certificate authority that signed your server's certificate. Three sources, in order of precedence:

1. Custom CA file — In the connection editor's SSL section, click Choose CA file... and pick a .crt or .pem file.
2. macOS keychain — If your CA is installed in the system or login keychain, QueryDeck picks it up automatically.
3. Bundled CA roots — QueryDeck ships with the same Mozilla CA bundle that ships with macOS. Most public CAs work without configuration.

To export the right CA from a cloud provider:

Client certificates (mTLS)

If your server requires mutual TLS, QueryDeck supports client certificates:

1. In the SSL section, expand "Advanced".
2. Provide both a client certificate file and a client key file.
3. If the key is encrypted, enter the passphrase. It's stored in the macOS Keychain.

mTLS is rare for managed databases but common in enterprise self-hosted setups.

SSL through an SSH tunnel

You can stack SSL on top of an SSH tunnel. The connection looks like:

QueryDeck  ──[SSH tunnel]──>  bastion  ──[SSL+TCP]──>  database server

The SSH tunnel encrypts the hop to the bastion. The SSL handshake then runs end-to-end with the database server.

In the connection editor, enable both the SSH tunnel section and the SSL section. They don't interfere.

Common errors

SSL connection is required

Your provider requires SSL but the mode is set to disable or prefer and got downgraded. Switch to require.

server certificate is not trusted

You're on verify-ca or verify-full and the CA isn't in QueryDeck's trust store. Either:

• Switch to require (less safe, but works).
• Download your provider's CA cert and load it in the SSL section.

server certificate does not match hostname

You're on verify-full and the certificate's SAN/CN doesn't include the hostname you're connecting to. Common with AWS RDS read replicas where the cert is for the cluster hostname. Switch to verify-ca or use the cluster hostname.

unable to load private key

The client key file is in a format libpq doesn't understand, or the passphrase is wrong. Convert PKCS#8 keys to PEM with OpenSSL if needed.

What's next

• SSH tunnels when the database isn't directly reachable
• Connection troubleshooting for non-SSL errors
• Credentials and Keychain for how QueryDeck stores your passwords