Using DBeaver’s Built‑in SSH Tunnel for JDBC Connections to Private Databases

Practical takeaway

When you enable the SSH tunnel option in a DBeaver connection profile, the client creates a local port forward to an SSH bastion before the JDBC driver opens the socket. The driver then connects to 127.0.0.1 on that forwarded port, and DBeaver tears down the forward when you disconnect. From the driver’s perspective the connection appears to be a normal TCP connection to the database host.

How the tunnel is wired into the connection

In the connection settings dialog most JDBC drivers expose an SSH tab. Enabling Use SSH tunnel tells DBeaver to:

1. Open an SSH session to the bastion host using the supplied username and authentication method (password or private key).
2. Request a local port forward (-L) to the database host and port as seen from the bastion.
3. Replace the host and port values in the JDBC URL with 127.0.0.1 and the locally forwarded port.
4. Start the JDBC connection; when the connection is closed, terminate the SSH session.

Each connection profile maintains its own SSH session; there is no shared tunnel pool across profiles.

Worked example: PostgreSQL behind a bastion

The table below shows a typical configuration for a PostgreSQL instance that is only reachable from inside a VPC.

Setting	Example value	Notes
Main tab – Host	db-internal.vpc.internal	DNS name resolvable from the bastion
Main tab – Port	5432	PostgreSQL default port
SSH tab – Use SSH tunnel	Enabled	Activates the forward
SSH tab – Host / Port	bastion.example.com / 22	Publicly reachable jump host
SSH tab – User name	deploy	OS account on the bastion
SSH tab – Authentication method	Public key	Preferred for automation; password also works
SSH tab – Private key file	~/.ssh/id_rsa	Path stored per profile; passphrase prompted at connect

After saving, test the connection. DBeaver will show the JDBC URL pointing to 127.0.0.1 with an ephemeral port, confirming the tunnel is in use.

Limits and common mistakes

Authentication and key file permissions

DBeaver reads the private key file via its SSH library. If the file is not readable by the process (e.g., incorrect permissions on Linux/macOS) the tunnel will fail to start, often surfacing as a JDBC timeout. Ensure the key file is readable by the user running DBeaver:

chmod 600 /path/to/private_key

Replace /path/to/private_key with the actual path. The expected result is a file mode of -rw-------.

Error diagnostics

When the SSH leg fails, DBeaver typically reports a JDBC connection timeout or "host unreachable" because the driver is trying to connect to a local port that has no listener. There is no separate SSH error dialog. To troubleshoot:

• Verify bastion reachability (ssh -v bastion.example.com).
• Confirm the private key and passphrase are correct.
• Check security groups or firewall rules that allow the bastion to reach the database host.

Lifecycle and resource usage

Each active connection spawns its own SSH session. Multiple profiles using the same bastion will create multiple tunnels, increasing load on the bastion and consuming local ports. There is no built‑in pooling of tunnels across profiles.

Latency and failure impact

The SSH hop adds latency and introduces a single point of failure. If the bastion connection drops, active database sessions are terminated and any open transactions may be left in an uncertain state. Use the tunnel for interactive administration or ad‑hoc queries rather than high‑frequency automated workloads.

Double encryption

Enabling both the SSH tunnel and JDBC SSL encrypts traffic twice. In most private‑network scenarios this adds CPU and latency overhead without additional security benefit. Enable only one transport protection unless your compliance regime explicitly requires both.

Credential storage

SSH passwords saved in a profile are stored in DBeaver’s secure vault, which is protected by the application master password. Changing the master password can invalidate stored credentials, requiring re‑entry. Private key passphrases are prompted interactively by default and are not stored unless you explicitly choose to save them.

Verifying the tunnel is active

While a connection is open, you can check for the local forwarded port:

# Linux/macOS
netstat -an | grep LISTEN | grep 127.0.0.1
# Windows
netstat -an | findstr LISTENING | findstr 127.0.0.1

You should see a line showing a listening socket on 127.0.0.1 with an ephemeral port (e.g., 127.0.0.1:54321). The socket disappears when you disconnect. No special privileges are needed to run these commands.