An SSH local tunnel created with ssh -L 5432:localhost:5432 user@server opens port 5432 on your machine and forwards every connection, encrypted inside SSH, to the server’s PostgreSQL. The database keeps listening only on the remote localhost, with no port exposed to the Internet, and your client connects to 127.0.0.1 as if it were local.
How ssh -L 5432:localhost:5432 works, step by step
The -L syntax is [bind_address:]local_port:dest_host:dest_port, and the destination host is resolved from the SSH server, not from your machine. That is why the localhost in the middle means “the remote box”. The full reference lives in the official ssh manual page.
# Foreground tunnel, no remote shell
ssh -N -L 5432:localhost:5432 [email protected]
# In another terminal, connect as if PostgreSQL were local
psql -h 127.0.0.1 -p 5432 -U app db_name-L 5432:localhost:5432: listens on local 5432 and delivers traffic to port 5432 on the server.-N: runs no remote command; the connection exists only to carry the tunnel.-f(optional): sends ssh to the background after authentication.
If the database runs on another host in the internal network, change the destination: ssh -N -L 5432:db.internal:5432 admin@bastion. The hop between the bastion and db.internal is no longer encrypted by SSH, so only do this on a trusted network. By default ssh binds the local port to the loopback interface; don’t expose it on 0.0.0.0 or enable GatewayPorts unless you know who else can reach your machine.
If a local PostgreSQL already owns port 5432, ssh reports bind: Address already in use. Pick another local port, such as -L 15432:localhost:5432, and connect with -p 15432.
LocalForward in ~/.ssh/config: the SSH tunnel without memorising flags
LocalForward is the ssh_config directive equivalent to -L: local port first, then the destination host:port, separated by a space.
Host db-prod
HostName server.example.com
User admin
IdentityFile ~/.ssh/id_ed25519
LocalForward 15432 localhost:5432
ExitOnForwardFailure yes
ServerAliveInterval 30With this block, ssh -N db-prod is all you type. Three choices in the example:
- Local port 15432: avoids clashing with a PostgreSQL already listening on your machine’s 5432.
- ExitOnForwardFailure yes: if the local port is taken, ssh exits instead of opening a session that looks fine but has no tunnel.
- ServerAliveInterval 30: sends a keepalive every 30 seconds so a dead connection is detected sooner.
OpenSSH is strict about permissions: ~/.ssh at 700 and the private key at 600. Every directive is listed in the official ssh_config documentation.
Checking that the SSH local tunnel listens and connects
The classic symptom of a broken tunnel is Connection refused in the database client; before touching PostgreSQL, test each end on its own.
# On your machine: is anything listening on the local port?
ss -ltn | grep 15432 # Linux
lsof -iTCP:15432 -sTCP:LISTEN # macOS
# On the server: is PostgreSQL listening on loopback?
ss -ltn | grep 5432
# Debug ssh itself
ssh -v -N db-prodWith -v you’ll see whether the server refuses the forward with an administratively prohibited message. In sshd_config, AllowTcpForwarding no disables tunnels; also check for Match blocks that restrict it for specific users.
SSH local tunnel from a phone: what changes compared with a desktop
Mosh does no port forwarding: it carries the session over UDP, by default on ports 60000-61000, and uses SSH only to start mosh-server. An -L tunnel needs a classic SSH connection open for as long as you use it, and iOS and Android may suspend apps that move to the background.
| Access method | Forwards ports? | What it requires | Best fit |
|---|---|---|---|
| ssh -L on a desktop | Yes, TCP inside SSH | Reachable port 22 and AllowTcpForwarding enabled | Graphical database clients, migrations from your machine |
| Mosh on iOS/Android | No | UDP 60000-61000 and mosh-server on the host | A shell that survives switching from wifi to mobile data |
| psql on the server, inside tmux | Not needed | SSH or Mosh session and psql installed | Quick queries from a phone |
| Mesh network (Prialo, Tailscale) | No; direct access by private IP | An agent on each device | Regular access with no open ports or tunnels |
From a phone, the practical route is usually to connect with Mosh, attach to tmux and run psql on the server itself. With a mobile SSH and Mosh terminal such as termi1, the session survives network changes, tmux keeps the long query you left running, and the built-in keyboard provides Ctrl, Tab and arrow keys to walk psql’s history or quit with Ctrl+D. The AI turns “connect to the app database” into the command and types it at the prompt without pressing Enter; on connections tagged as production, Production Guard holds back anything that deletes or changes data. Built-in SFTP lets you download a pg_dump file without leaving the session.
When not to use an SSH local tunnel (-L)
An -L tunnel is a one-off fix for one person and one session; outside that case there is usually a better option.
- Permanent or shared access: if several people need the database every day, a private network without open ports such as Prialo or Tailscale beats maintaining individual tunnels.
- Mosh sessions: Mosh doesn’t forward ports; if you need the tunnel, open a separate SSH connection.
- Binding to 0.0.0.0 or using GatewayPorts: it turns your laptop into a gateway to the database for the whole local network.
- Servers with AllowTcpForwarding no: that is an admin policy, not a bug to work around.
- One-off queries from a phone: running psql on the server is simpler than keeping a tunnel alive.
Frequently asked questions
What does localhost mean in ssh -L 5432:localhost:5432?
In ssh -L 5432:localhost:5432, localhost is resolved by the SSH server, not by your machine. It therefore points to the PostgreSQL listening on the remote host’s loopback interface. To reach another machine on the internal network, replace it with that host’s name or private IP.
How do I run an SSH local tunnel in the background?
An SSH local tunnel runs in the background with ssh -f -N -L 15432:localhost:5432 admin@server: -f sends ssh to the background after authentication and -N skips the remote shell. To close it, find the process with pgrep -f 15432 and stop it with kill.
Can Mosh forward ports like an SSH tunnel?
Mosh cannot forward ports: it supports neither port forwarding nor X11 forwarding and carries the session over UDP, by default on ports 60000-61000. Forwarding a port requires a regular SSH connection, which can run alongside the Mosh session at the same time.
Is an SSH local tunnel to a production database safe?
An SSH local tunnel to production encrypts traffic and avoids exposing the database port to the Internet, but any process on your machine can use the forwarded port while it stays open. Bind it only to 127.0.0.1, close it when finished and use a least-privilege database user.