SSH Tunnel
Connect to a PostgreSQL database through an SSH bastion host using password or private key authentication.
An SSH tunnel routes tpaw's database connection through a secure shell connection to a bastion (jump) host. This lets you connect to databases that aren't directly accessible from your machine — common in production environments where PostgreSQL is on a private network.
How it works
When SSH tunnel is enabled, tpaw:
- Establishes an SSH connection to the bastion host
- Opens a local port forward through that SSH connection
- Routes the PostgreSQL protocol through the tunnel
Your PostgreSQL server sees the connection coming from the bastion, not your local machine.
Enabling SSH tunnel
In the connection form, scroll to the SSH Tunnel section and toggle Use SSH Tunnel.
SSH tunnel fields
| Field | Required | Notes |
|---|---|---|
| SSH Host | Yes | Hostname or IP of the bastion server |
| SSH Port | Yes | Default: 22 |
| SSH Username | Yes | Your user on the bastion host |
| Auth Method | Yes | Password or Key File |
| Password | If password auth | SSH password (not database password) |
| Private Key Path | If key file auth | Path to .pem or private key file |
| Passphrase | No | If the private key has a passphrase |
Authentication methods
Password: Enter the SSH password for the bastion host. This is separate from the PostgreSQL password.
Key File: Click Browse to select a private key file. tpaw accepts .pem, .key, and standard OpenSSH key formats. If the key has a passphrase, enter it in the Passphrase field.
Example configuration
For a database on a private AWS RDS instance behind an EC2 bastion:
| Field | Value |
|---|---|
| Host (PostgreSQL) | db.internal.example.com |
| Port | 5432 |
| SSH Host | bastion.example.com |
| SSH Port | 22 |
| SSH Username | ec2-user |
| Auth Method | Key File |
| Private Key | ~/.ssh/my-key.pem |
Troubleshooting SSH tunnel issues
SSH tunnel: connection refused
- Verify the bastion is reachable:
ssh ec2-user@bastion.example.com - Check that port 22 is open on the bastion's security group
SSH tunnel: authentication failed
- For key auth: ensure the public key is in
~/.ssh/authorized_keyson the bastion - For password auth: verify the password is correct
- Check that password authentication is enabled on the bastion (
PasswordAuthentication yesin sshd_config)
SSH tunnel: channel open failed
- The bastion can't reach the PostgreSQL host — check internal DNS and firewall rules between the bastion and the database server
Connection times out after connecting through tunnel
- Some SSH servers have aggressive keepalive timeouts — the connection may drop while idle. Reconnect if you see timeout errors.