SSH tunnel to PostgreSQL from iPhone

Production databases belong off the internet. HeapDeck reaches yours the way your laptop does: through your bastion, with your key, and with no server of ours in between.

Updated · Vladimir Chemeris, the developer of HeapDeck

Download on the App Store
Scan to open it on your iPhone

Free · Pro $19.99 one-time · PostgreSQL 13–19 · iOS 17+ · iPhone and iPad

Verify this server sheet: the certificate's names and issuer, its SHA-256 fingerprint and expiry date, shown before HeapDeck trusts it

The tunnel, end to end

In a connection’s settings, turn on Use SSH tunnel and fill in the bastion’s host, port (22 by default) and user. HeapDeck opens an SSH session from your iPhone to the bastion and asks it to forward a connection to the database host and port you entered, the same direct-tcpip channel ssh -L uses. The PostgreSQL protocol then runs inside that channel, with TLS on top according to the connection’s sslmode.

If the database sits deeper, Add jump host turns the bastion into a route of two or three hosts, each with its own login. Your iPhone opens TCP to the first host only and reaches each next host through the one before; the last host opens the database. Enter the database host as the last host sees it: a private address like 10.0.0.5 works as long as that host can reach it.

How HeapDeck signs in

Each host on the route takes a password, a private key or a Secure Enclave key.

  • Private key: Ed25519, ECDSA or RSA, in OpenSSH, PEM, PKCS#8 or PuTTY PPK v2/v3 format. Import it from Files or paste it. HeapDeck shows the key’s SHA-256 fingerprint, so you can compare it with ssh-keygen -lf on your laptop. An encrypted key asks for its passphrase once, and the key and passphrase go to the iOS Keychain on this iPhone, with no sync.
  • Secure Enclave key: an ECDSA P-256 key that HeapDeck creates inside the phone’s chip. The private key never leaves the device, not even into a backup. You choose whether each new SSH connection asks for Face ID or your passcode, Face ID only, or nothing.

If the bastion asks for a one-time code, HeapDeck shows its question in a sheet and keeps the code nowhere. An old bastion that accepts RSA signatures only with SHA-1 gets an Allow ssh-rsa (SHA-1) switch for that bastion after the first refusal.

The safest setup is a key made for HeapDeck alone that can do nothing but forward to the database:

ssh-keygen -t ed25519 -C heapdeck -f heapdeck_ed25519

Or create a Secure Enclave key in HeapDeck and copy its public line. On the bastion, add the public key to ~/.ssh/authorized_keys with options that limit it to this one forward:

restrict,port-forwarding,permitopen="10.0.0.5:5432" ssh-ed25519 AAAA… heapdeck

restrict turns off shells, agent forwarding and the rest; port-forwarding and permitopen give back a single destination. If you lose the phone, delete that line and the key stops working, while everyone else keeps their access.

Pinned host keys and certificates

The first time you connect, HeapDeck shows each host’s key fingerprint and asks you to compare it with what ssh-keygen -lf prints on that host; on a route, each jump host gets its own sheet. HeapDeck remembers a key once you trust it. If a key changes, HeapDeck refuses with This bastion’s host key changed, and that sheet has no button to trust it. Check with whoever runs the bastion, tap Forget the saved key…, and verify the new key on the next connect.

The database’s TLS certificate works the same way under sslmode=require: HeapDeck shows its names, issuer and SHA-256 fingerprint once and pins it to the route. Two localhost:5432 databases behind different bastions keep separate pins.

If it doesn’t connect

Test connection walks the whole path, Local Network permission, each SSH host, TLS and login, then reports where it stopped. On a route, each host gets its own line, and the hosts after a failure read not reached. A result like The tunnel is fine — this is PostgreSQL rejecting the credentials tells you to leave SSH alone. Typical messages:

  • SSH tunnel failed. Check bastion host / key.: the bastion is unreachable or refused the forward.
  • SSH auth failed. Check bastion username / password / key.: a wrong user or password, or a key the host doesn’t list in authorized_keys.
  • SSH host key changed — possible MITM. Connection refused.: the bastion presented a different host key and you didn’t trust it.

A key HeapDeck can’t read shows This key can’t be used when you import it, with the reason and the command that converts it.

Limits

A route holds up to three SSH hosts. A Secure Enclave key stays with the device that created it. DSA keys, hardware sk-* keys, PuTTY PPK v1 and keys protected with chacha20-poly1305, 3DES or scrypt don’t work yet. A two-factor bastion asks for a code on every new SSH connection. HeapDeck doesn’t support client certificates (mTLS).

Questions

Can I connect to a private Postgres database from my iPhone?

Yes, through an SSH bastion that can reach it. HeapDeck tunnels from the phone to the bastion and on to the database. Enter the database host as the last host on the route sees it.

Does HeapDeck support SSH keys with a passphrase?

Yes. It imports Ed25519, ECDSA and RSA keys in OpenSSH, PEM, PKCS#8 and PuTTY PPK v2/v3 formats, with or without a passphrase. Keys stay in the iOS Keychain on the phone, with no sync.