Configure an SSH Tunnel in DBeaver for Private Database Connections

Use an SSH tunnel when the database is not directly reachable

If your database sits behind a bastion host or in a private network, exposing its port to the internet is usually unacceptable. DBeaver can forward database traffic through an intermediate SSH host instead. The useful takeaway: enable the SSH tunnel on the connection editor's SSH tab, point the database connection at the address reachable from the bastion, and let DBeaver open and close the tunnel with the connection.

Worked configuration: PostgreSQL through a bastion

This example uses DBeaver Community Edition. Your edition's SSH tab labels may differ, so check your installed version's help if a field name does not match.

1. Open Database > Edit Connection or create a new connection.
2. On the main tab, set the database type, host, port, database name, and credentials. Use the host address that the bastion can reach, such as db.internal.example.com on port 5432. This address does not need to be reachable from your laptop.
3. Switch to the SSH tab and enable Use SSH tunnel.
4. Enter the bastion details:
• SSH host: bastion.example.com
• SSH port: 22
• User name: deploy
• Authentication method: Private key
• Private key file: /home/yourname/.ssh/id_ed25519 on Linux or macOS, or %USERPROFILE%\.ssh\id_ed25519 on Windows
5. If the key is passphrase-protected, enter the passphrase. DBeaver may require a master password or operating-system keychain integration to store it.
6. Click Test Connection. A successful result means DBeaver authenticated to the bastion and reached the database through the tunnel.

Field	Example value	Notes
SSH host	bastion.example.com	Intermediate host with network access to the database
SSH port	22	Default SSH port
SSH user name	deploy	Account on the bastion
Authentication method	Private key	Password authentication is also supported
Private key file	/home/yourname/.ssh/id_ed25519	Use an absolute path; tilde expansion is not reliable across editions
Database host	db.internal.example.com	Address reachable from the bastion, not necessarily from your laptop
Database port	5432	Database listener port

How DBeaver manages the tunnel

A bastion host is an intermediate server used to reach a private network. DBeaver uses local port forwarding: it opens a local port on your machine and forwards traffic through the SSH session to the bastion, which connects to the database. The tunnel lifecycle is tied to the DBeaver connection. Opening the connection establishes the tunnel; closing the connection tears it down. You do not run a separate ssh command.

Verify the result

1. Run Test Connection in the connection editor. Success confirms SSH authentication and database reachability through the bastion.
2. Open the connection and run a simple query, such as SELECT 1.
3. If the connection fails, inspect the DBeaver connection log for SSH authentication errors, host-key prompts, or refused connections.
4. Confirm that the bastion firewall allows your client IP on port 22, and that the database accepts connections from the bastion's IP address.

Limits and common mistakes

• Latency and throughput: Every query crosses the SSH tunnel, so a high-latency bastion slows result sets, and large exports can saturate the tunnel.
• Shared resources: Concurrent connections through one tunnel share bandwidth and can reach tunnel-level or bastion connection limits.
• Wrong database host: Setting the database host to your laptop's localhost usually fails unless the database actually runs on the bastion. Use the address reachable from the bastion.
• Credential storage: Without a master password or OS keychain integration, stored SSH keys and passwords may be less protected. Configure a master password in DBeaver if you store private keys.
• Firewall direction: The database must allow the bastion's address, not your laptop's address.
• Edition differences: SSH tab labels and keychain behavior vary between DBeaver Community, Lite, and Enterprise editions.

Remove or disable the tunnel

Because this changes the connection configuration, rollback means disabling the tunnel and testing direct connectivity:

1. Open Database > Edit Connection.
2. On the SSH tab, clear Use SSH tunnel.
3. Click Test Connection. If the database is directly reachable, the test succeeds. If it fails, the tunnel is still required and network access must be restored before direct connections work.

Practical check: Temporarily disable the tunnel and attempt a direct connection. If direct access works, your network path is open; if it does not, confirm bastion and database firewall rules before re-enabling the tunnel.