SSH & TLS

Reach databases through an SSH tunnel or jump hosts, and encrypt and verify connections with TLS.

Both options live in the connection form, below the Server section. They apply to PostgreSQL, MySQL / MariaDB, SQL Server, Redis and MongoDB connections.

SSH tunnel

Use an SSH tunnel when the database is only reachable from a server inside its network, such as a bastion host.

Open the connection form and turn on Connect over SSH in the SSH Tunnel section.
Fill in SSH host, SSH port and SSH user.
Choose an Authentication method and enter its secret.
In the Server section, set Host and Port as seen from the SSH server — for example 127.0.0.1 or a private DNS name.
Click Connect.

Field	Default	Description
SSH host	—	The SSH server to log in to.
SSH port	`22`
SSH user	Your macOS user name
Authentication	—	Password, Private key or SSH agent.
Keep-alive (seconds)	`30`	How often to check the tunnel. `0` turns it off.

Authentication

Password — enter the SSH password.
Private key — set the Private key path (~/.ssh/id_ed25519 by default) or click Choose…, which opens ~/.ssh with hidden files visible. Enter the Key passphrase if the key has one.
SSH agent — uses the keys loaded in an SSH agent. Leave Agent socket empty to use the system agent, or paste the socket path of another agent, such as 1Password or Secretive.

SSH passwords and key passphrases are stored in the macOS Keychain.

Supported keys

ed25519
ECDSA (P-256, P-384 and P-521)
RSA, signed with rsa-sha2-512 or rsa-sha2-256

Keys can be in OpenSSH format or unencrypted PEM.

Encrypted PEM keys aren't supported. Convert the key to OpenSSH format, or load it into an SSH agent instead.

Using the system agent

With SSH agent and an empty Agent socket, Mantidb uses the same agent as Terminal. That includes keys whose passphrase you saved in the macOS Keychain with:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Keep-alive

Mantidb sends a keep-alive message (keepalive@openssh.com) every Keep-alive (seconds). If the server misses three answers in a row, the tunnel is dropped, and Mantidb reconnects it automatically the next time it talks to the database.

Host key verification

The first time you connect to an SSH server, Mantidb asks Trust SSH server host:port? and shows the key's algorithm and fingerprint.

Click Trust and Connect to save the key and continue.
Click Cancel if the fingerprint isn't the one you expect.

After that, if the server presents a different key, the connection is rejected.

Jump hosts

Jump hosts work like OpenSSH's ProxyJump: Mantidb logs in to each hop in order and then reaches the SSH server from the last one.

In the Jump Hosts section, click Add Jump Host.
Fill in Jump host, Jump port, Jump user, Authentication and its secret for the new hop (Hop 1, Hop 2…).
Click the minus button to remove a hop.

Each hop has its own trusted host key and its own Keychain secret.

You can also set jump hosts in a connection URL with the jump parameter.

Mantidb doesn't read ~/.ssh/config. Enter hosts, users, keys and jump hosts in the form.

TLS

The TLS section sets how the connection is encrypted and how the server's certificate is checked. The default is Prefer.

Mode	What it does
Disable	Traffic is not encrypted.
Prefer	Encrypts when the server supports it. The certificate is not checked.
Require	Always encrypts. The certificate is not checked.
Verify CA	Always encrypts. The certificate must chain to the CA certificate file, or to a CA your Mac trusts.
Verify Full	Like Verify CA, and the certificate must also name the server.

Extra fields

Field	Shown for	Description
CA certificate	Verify modes	The CA file to trust. Empty uses the System trust store.
Server name	Verify modes	The name the certificate must match. Empty uses the host.
Client certificate	Any encrypted mode	A PEM certificate for client authentication.
Client key	Once a client certificate is set	The key for the client certificate. Empty means it's In the certificate file.

For Amazon RDS, choose Verify CA or Verify Full and use AWS's global-bundle.pem as the CA certificate.

Encrypted client keys aren't supported.

TLS over SSH

With Verify Full over an SSH tunnel, Mantidb checks the certificate against the real database host — not the tunnel — and sends it as the server name (SNI). If the certificate uses a different name, for example because the host is an IP address, enter it in Server name. Without it, the connection fails with a clear error.

Engine notes

PostgreSQL and MySQL / MariaDB support every mode.
SQL Server encrypts with up to TLS 1.2.
Redis and MongoDB can't negotiate TLS, so Prefer means no encryption. Choose Require or a verify mode to encrypt. For Redis, a rediss:// URL turns TLS on.