Connect to a database over an SSH tunnel

Databases should not be open to the internet. An SSH tunnel lets your computer reach a database that listens only on the server's localhost, using the SSH connection you already have. The database port never leaves the server.

Before you begin

• A working SSH key login to your VPS. Password logins are fine for setup, but keys are safer and needed for smooth tunnels.
• A database running on the server and bound to localhost, such as PostgreSQL (port 5432), MariaDB (3306) or Redis (6379).
• A client on your computer: psql, the mariadb client, a GUI tool, or similar. Windows 10 and 11 include an OpenSSH client.
• A sudo user on the server, such as alex, with the VPS address 203.0.113.10 (replace it with yours).

Step 1: Confirm the database is bound to localhost

On the server, check which address each database port uses. A tunnel only needs localhost on the server side, so the usual result is 127.0.0.1.

sudo ss -tlnp | grep -E '5432|3306|6379'

LISTEN 0  200  127.0.0.1:5432  0.0.0.0:*
LISTEN 0   80  127.0.0.1:3306  0.0.0.0:*

If a database shows 0.0.0.0, reconfigure it to listen on localhost before you continue. Publicly reachable databases are a common route for break-ins.

Step 2: Open a tunnel from your computer

Run this on your laptop, not on the server. The options work like this:

• -N means do not run a remote command; only forward ports.
• -L 15432:localhost:5432 means: listen on port 15432 on my computer, and send traffic to port 5432 as seen from the server.

ssh -N -L 15432:localhost:5432 alex@203.0.113.10

The terminal will look idle, which is expected. Leave it open while you work. Port 15432 is used locally, so it does not clash with a PostgreSQL install on your own computer. Press Ctrl+C in this window to close the tunnel.

Step 3: Connect through the tunnel

In a second terminal on your computer, connect to the forwarded port on localhost:

psql -h localhost -p 15432 -U alex -d appdb

Enter the database password when asked. To tunnel MariaDB as well, add a second -L option to the same SSH command, using a different local port:

ssh -N -L 15432:localhost:5432 -L 13306:localhost:3306 alex@203.0.113.10
mariadb -h 127.0.0.1 -P 13306 -u alex -p appdb

Use 127.0.0.1 rather than localhost for MariaDB clients, because some MariaDB tools treat the word localhost as a local socket path.

Step 4: Save the tunnel as a short command

Typing the full command each time gets tedious. On your computer, add an entry to your SSH config file. Open it with:

nano ~/.ssh/config

Add this block and save:

Host example-db
    HostName 203.0.113.10
    User alex
    LocalForward 15432 localhost:5432

Now the tunnel starts with ssh -N example-db. Set the file's permissions so only you can read it:

chmod 600 ~/.ssh/config

Step 5: Run the tunnel in the background (optional)

The -f option sends SSH to the background once authenticated. To see which tunnels are running, and to stop one, use the process ID:

ssh -fN example-db
pgrep -a ssh
kill 12345

Replace 12345 with the process ID shown by pgrep. Make sure the ID belongs to the tunnel and not to your normal SSH sessions.

Troubleshooting

• bind: Address already in use: another program on your computer uses that local port. Choose a different one, such as 25432, and update the connection.
• Connection refused in psql: the tunnel is not running, or you used the wrong port. Check the tunnel terminal for errors.
• channel open failed: connect failed: the server-side database is not listening on the port you forwarded. Run the check in Step 1.
• Password prompt keeps repeating: the database role or password is wrong. The tunnel itself is working, so check the database login.

Next steps

Once tunnels work, you can leave your databases private and still manage them comfortably. Keep the database backup guides close at hand, since a private database still needs regular copies.