Skip to content

TLS and sslmode

Choose how a connection uses TLS with its Encryption field. The stronger settings prove you reached the right server, not only that nobody can read the traffic.

What each setting checks

Section titled “What each setting checks”
Encryption sslmode Encrypts Checks the certificate Checks the host name
Required, verify server verify-full Yes Yes Yes
Required, verify certificate verify-ca Yes Yes No
Required require Yes Only when CA certificate is set No
Preferred prefer When the server offers it Only when CA certificate is set No
Off disable No No No

Preferred is the default. It tries TLS first, and connects in plain text when the server answers that it does not support SSL. Anyone between you and the server can give that answer, so Preferred protects nothing you can count on.

The form shows CA certificate only for Required and stricter, but a pasted URL with sslmode=prefer and sslrootcert keeps its CA file. Preferred then checks the certificate’s chain whenever TLS is used, as Required does. It still connects in plain text when the server refuses TLS.

A pasted URL with sslmode=allow becomes Off: Alcuin connects in plain text and does not retry with TLS.

“Checks the certificate” means the server’s certificate must chain to an authority Alcuin trusts. By default that is a built-in list of public authorities. Set CA certificate to a PEM file to trust that authority instead.

“Checks the host name” means the certificate must name the Host you typed. Through an SSH tunnel set up in Alcuin, the check still uses the Host field, so Required, verify server works there too.

Choose a setting

Section titled “Choose a setting”
Your server Choose
A cloud provider that publishes its CA file (Amazon RDS and Aurora, Supabase, DigitalOcean) Required, verify server, with CA certificate set to that file
Cloud SQL, connecting directly to the instance’s IP address Required, verify certificate, with its server-ca.pem
A certificate from a public authority (Neon, Azure Database for PostgreSQL) Required, verify server, with no CA file
You connect by IP address, or through a port forward on localhost, so the certificate names another host Required, verify certificate, with the CA file
A server with TLS whose CA you cannot get, such as a self-signed certificate Required, and ask for the CA file
Postgres on this machine, without TLS Preferred or Off

Choose Required, verify server whenever the provider gives you a CA. It is the only setting that proves you reached the right server.

Set the certificate files

Section titled “Set the certificate files”

When Encryption is Required or stricter, three more fields show. They are libpq’s sslrootcert, sslcert and sslkey, and a pasted URL fills them in.

Field What it takes
CA certificate A PEM file the server’s certificate must chain to. Type system instead of a path to trust your operating system’s authorities as well as the built-in list.
Client certificate A PEM certificate, for a server that asks the client for one.
Client key The PEM key for that certificate, without a passphrase. Set both or neither.

Alcuin reads the files at each connect, so a renewed file takes effect on the next one. A path may start with ~/.

In a URL, sslrootcert=system means Required, verify server, as it does in libpq. A URL that names a CA file and no sslmode becomes Required, verify certificate, and one that names only a client certificate or key becomes Required.

Where each provider’s root certificate comes from

Section titled “Where each provider’s root certificate comes from”
Provider Root certificate
Amazon RDS and Aurora AWS’s bundle for every region, global-bundle.pem. Set CA certificate to it.
Supabase Your project’s root certificate, which Supabase offers for download in the project’s database settings.
Neon A public authority. No file needed.
Azure Database for PostgreSQL Public authorities. No file needed.
Cloud SQL The instance’s server CA certificate, server-ca.pem, which you download from the instance.
DigitalOcean The cluster’s CA certificate, which DigitalOcean offers for download with the cluster’s connection details.

Cloud providers has a full recipe for the first five.

Saved passwords follow the encryption

Section titled “Saved passwords follow the encryption”

A saved password is kept with the encryption it was saved under: the Encryption setting, the CA it trusts, and the SSH server’s key. If you weaken any of them later, Alcuin asks before it sends the password: Send the saved password for … over a less protected connection?, with Don’t send as the default.

Separately, when a server asks for the password in clear text or as MD5, Alcuin sends it only over TLS that checks the certificate, an SSH tunnel, or to a server on this machine. Otherwise the connect stops at Sign in with:

The server asked for the password in clear text, and this connection doesn't check the server's certificate, so Alcuin didn't send it.

This holds for a password from .pgpass too. Set Encryption to Required, verify server (with the server’s CA where it has its own), or have the server use SCRAM (password_encryption = scram-sha-256).

Channel binding

Section titled “Channel binding”

Alcuin does not use channel binding yet. A channel_binding parameter in a pasted URL is ignored, and SCRAM sign-in goes ahead without it. Not supported yet lists what else Alcuin doesn’t do.

When encryption fails

Section titled “When encryption fails”

Test connection names the failing step Couldn't set up encryption. Connection errors by message has each message and its fix:

When a connection without an SSH tunnel works, Test connection says over TLS if the session is encrypted and directly if it is not. With Preferred, directly means the server did not offer TLS.