DBeaver SSH Tunnel: Connect to Private Databases Through a Bastion

The Problem: Private Databases Block Direct Connections

Your database accepts connections only from inside a private network. A bastion host is the only SSH-accessible gateway. Opening a terminal and running ssh -L before every DBeaver session works, but it is manual, easy to forget, and not saved with the connection.

DBeaver can bind the tunnel to the connection definition itself. When you connect, DBeaver authenticates to the bastion, opens a local forwarding port, and tells the JDBC driver to use that local endpoint. Close the connection and the tunnel ends.

How DBeaver SSH Tunneling Works

In the connection editor, the SSH tab sits next to the Main JDBC tab. Enable Use SSH tunnel and provide:

• SSH Host — bastion hostname or IP.
• Port — typically 22.
• Username — bastion account.
• Authentication method — Public key or Password.

For public key auth, select the private key file. DBeaver can also use an SSH agent so the passphrase is not stored in DBeaver's configuration.

The Main tab is where most mistakes happen. Set Host to the database address as seen from the bastion, such as a private hostname or internal IP. Do not set it to localhost; localhost on the Main tab means the client machine, not the bastion. DBeaver rewrites the JDBC URL to connect to the locally forwarded port that reaches the bastion-routed database.

Worked Example: PostgreSQL Through One Bastion

Assume:

• Bastion: bastion.example.com, user ec2-user, key ~/.ssh/bastion_ed25519.
• Database: prod-db.internal.example.com, port 5432, reachable from the bastion.

First verify the route outside DBeaver. Run this in a terminal:

ssh -i ~/.ssh/bastion_ed25519 -L 15432:prod-db.internal.example.com:5432 [contact removed]

In another terminal, confirm the local forward works:

psql -h localhost -p 15432 -U app_user -d mydb

If that succeeds, create the DBeaver connection:

1. New connection to PostgreSQL.
2. Main tab: Host = prod-db.internal.example.com, Port = 5432, Database = mydb, Username = app_user.
3. SSH tab: Enable Use SSH tunnel. Host = bastion.example.com, Port = 22, User = ec2-user, Auth = Public key, Private key = ~/.ssh/bastion_ed25519.
4. Click Test Connection. Look for a successful tunnel or authentication message.
5. Save and connect. Check the connection log for the local port DBeaver assigned.

Run the terminal commands from your workstation, not inside DBeaver. Required permissions: read access to the private key file; on Linux or macOS the key should be chmod 600. A wrong Main-tab host can make the tunnel appear to succeed while database queries fail.

Limits and Common Mistakes

Throughput and Persistence

All traffic crosses an SSH-encrypted hop. Bulk exports, large COPY operations, and replication tools will be slower than a direct connection. The tunnel exists only while the DBeaver connection is open; it is not shared across connections and cannot serve background scripts. Use autossh or a system service for a persistent forward.

Multi-Hop Connections

DBeaver's SSH tab supports a single bastion. For workstation to bastion-a to bastion-b to database, write ProxyJump in ~/.ssh/config and point DBeaver at the final bastion host entry. DBeaver calls the system SSH client, which reads that config.

Diagnosis Table

Symptom	Likely Cause	Check
JDBC timeout after tunnel reports success	Main tab Host is localhost or unreachable from bastion	Run ssh bastion "getent hosts prod-db.internal.example.com" to confirm name resolution from the bastion.
Permission denied or auth fail	Wrong key, wrong user, or overly open key permissions	Run the standalone ssh -L test first. Verify chmod 600 ~/.ssh/bastion_ed25519.
Works once, fails on reconnect	Idle session dropped by bastion SSH settings	Add ServerAliveInterval 30 for the bastion in ~/.ssh/config.
Passphrase stored in DBeaver config	Passphrase entered in the key field instead of using an agent	Leave the passphrase blank; run ssh-agent and ssh-add before launching DBeaver.

Security Hygiene and Verification

DBeaver workspace metadata can record SSH key paths. Do not commit the workspace directory to version control. Prefer SSH agent authentication, restrict the DBeaver config directory (chmod 700 ~/.dbeaver4 on Linux or macOS), and add the workspace to .gitignore.

Before relying on the connection:

1. Standalone ssh -L test succeeds.
2. DBeaver Test Connection reports tunnel success.
3. Connection log shows the remote endpoint as the private database address.
4. Run SELECT 1 and confirm acceptable latency.

If the checks pass, the tunnel is wired correctly. For high-volume workloads, move the export closer to the database instead of pushing more data through the SSH tunnel.