DBeaver SSH Tunneling: Connecting to Databases Behind a Bastion Host

If your database listens only on a private network, DBeaver's built-in SSH tunnel lets you reach it from your workstation without a VPN or a publicly exposed database port. The feature works by making DBeaver act as an SSH client to a bastion host, then forwarding a local port to the database address as seen from that bastion. Configured correctly, the main connection Host field should contain the database hostname reachable from the bastion—not localhost.

How the tunnel works

DBeaver does not create a system-wide network route. Instead, when you enable SSH tunneling on a connection, DBeaver opens an SSH session to the bastion host you specify. Over that session, it asks the remote SSH server to forward a local port to the target database host and port. Database traffic then flows from DBeaver through the encrypted SSH channel to the bastion, and from the bastion to the database.

Because the tunnel is created per connection, each database connection in DBeaver that needs the bastion must have its own SSH settings. Duplicating a connection in the DBeaver navigator does not automatically copy the SSH configuration.

Worked configuration

Assume a PostgreSQL database at db.internal.example.com:5432 that is reachable only from a bastion host at bastion.example.com on port 22. Your SSH user on the bastion is deploy. Exact dialog labels can vary by DBeaver edition and version, so verify the wording in your installed copy.

1. Main connection settings

In the connection dialog, set the database Host to db.internal.example.com and the port to 5432. This is the address the bastion will use to reach the database, not the address your local machine uses.

2. SSH tab

Open the SSH tab and check Use SSH Tunnel. Then set:

• Host/IP: bastion.example.com
• Port: 22 (or your organization's non-standard SSH port)
• User Name: deploy
• Authentication: choose Password or Public Key depending on what the bastion accepts

If you select public-key authentication, point DBeaver to the private key file on your workstation. DBeaver's built-in SSH client may not support every key format or agent-forwarding option that native OpenSSH supports, so a key that works from your terminal may still fail inside DBeaver.

3. Test before browsing

Click Test Connection. DBeaver attempts the SSH handshake first, then tries to open the database connection through the forwarded port. A successful test confirms both the SSH authentication and the bastion's ability to reach the database port. Only after the test passes should you browse schemas or run queries.

Verifying traffic actually flows

A passing Test Connection button is necessary but not always sufficient. To confirm the tunnel forwards traffic correctly, run a trivial query such as SELECT 1; in DBeaver and compare the result with another database client that reaches the same database through a different path. If both return the expected value, the tunnel is forwarding traffic.

If the test fails, open the DBeaver error log. Look for SSH authentication failures, timeouts, or key-exchange errors. These messages distinguish between a bastion access problem and a database reachability problem.

Limits and common mistakes

The bastion must allow outbound database connections

SSH tunneling does not bypass network policy. The bastion host must be allowed to open outbound connections to the database port. Some managed cloud databases restrict access to specific IP ranges or private endpoints, which means even a correctly configured tunnel will fail if the bastion is not in the allowed list.

Do not set the main host to localhost

A frequent error is changing the main connection Host to 127.0.0.1 or localhost. That setting tells the bastion to connect to itself, not to the database. The main host must remain the database address as seen from the bastion.

SSH user needs bastion access, not database access

The SSH user you specify in the tunnel settings authenticates to the bastion host. That user does not need database credentials. However, the user must be permitted to log in to the bastion and must not be restricted by a forced command or chroot that blocks port forwarding.

Tunnels do not persist across connections

Each connection in DBeaver maintains its own tunnel. Closing the connection tears down the SSH session. If you open a second connection to the same database, configure its SSH tab independently.

Changing SSH settings requires reconnecting

If you modify SSH settings while editors are open, the active SQL editors may continue using the old tunnel. Close and reopen the connection, or reconnect the editor, so the new tunnel takes effect.

Multi-factor authentication may not work

DBeaver's built-in SSH client may not support interactive multi-factor authentication prompts. If your bastion requires MFA, the tunnel may fail even though your terminal client succeeds. In that case, check whether your DBeaver distribution supports an external SSH agent or an alternative authentication path.

Practical check

After configuring the tunnel, use this checklist:

1. Main Host equals the database address reachable from the bastion.
2. SSH tab has Use SSH Tunnel enabled with correct bastion host, port, and user.
3. Test Connection reports success.
4. SELECT 1; returns the same result as an independent client.

Because DBeaver editions and versions differ in dialog layout and SSH capabilities, verify the exact labels and supported options in your installed version. The underlying mechanism—DBeaver acting as an SSH client to forward a local port to the remote database—remains consistent.