Configure DBeaver to Connect to a Remote Database via an SSH Tunnel

Goal: Securely Connect DBeaver to a Remote Database Behind a Bastion

When a database is not exposed to the public internet, the typical way to reach it from a local workstation is via an SSH tunnel. DBeaver bundles an SSH client that can forward a local port to a remote host, letting the JDBC driver talk to the database as if it were running locally. This article walks through the entire process: from prerequisites, to configuration, to verification and recovery.

Prerequisites

• SSH Credentials: A user account on the bastion host that can log in and forward ports. Either a password or a private key that is accepted by the SSH daemon.
• Network Reachability: From the bastion, the database host must be reachable on its listening port (e.g., 5432 for PostgreSQL, 3306 for MySQL).
• JDBC Driver: The correct driver for your database must be installed via DBeaver’s Driver Manager. If you’re using PostgreSQL, for example, download the latest PostgreSQL JDBC driver.
• Permissions: If you use a private key, the key file on your local machine must have 600 permissions (no write for group/others). On Windows, ensure the file is not blocked by the OS.
• DBeaver Edition: SSH tunneling is available in the Community Edition. If you’re on the Enterprise Edition, the same steps apply, but confirm that the SSH library bundled with your version supports the key format you plan to use.

Step‑by‑Step Configuration

1. Create a New Connection

   Open DBeaver, click New Database Connection (or press Ctrl+Alt+N). Choose your database type (e.g., PostgreSQL) and click Next.

2. Fill in the Main Tab
   • Host: localhost (the local end of the tunnel).
   • Port: 5432 (or the port you will forward).
   • Database: mydb.
   • Username / Password: Database credentials (not SSH credentials).
3. Open the SSH Tab

   Click the SSH tab to enable tunneling.

   • Use SSH tunnel: Check this box.
   • Host: bastion.example.com (public IP or DNS of the bastion).
   • Port: 22 (default SSH port).
   • Username: deployuser.
   • Authentication:
     • For password: select Password and enter it.
     • For key: select Public key, browse to /home/me/.ssh/id_rsa, and optionally provide the passphrase.
   • Local port: Leave blank to let DBeaver choose a random free port.
   • Remote host: db.internal.local (the hostname or IP of the database server as seen from the bastion).
   • Remote port: 5432 (database listening port).
   • Keep‑alive interval: Optional. Set to 60 seconds to avoid idle drops on long‑running sessions.
4. Test the Tunnel

   Click the Test tunnel configuration button. DBeaver will attempt to establish an SSH session and open the forwarded port. A green tick indicates the tunnel is up.

5. Test the Full Connection

   Click Test Connection on the main tab. DBeaver will use the JDBC driver to connect to localhost:5432 (the forwarded endpoint). A successful test confirms both SSH and JDBC layers are functional.

6. Save the Connection

   Give the connection a meaningful name, e.g., Prod‑Postgres‑Bastion, and click Finish.

Verification Checklist

• SSH Tunnel Test: Green tick on Test tunnel configuration.
• JDBC Connection Test: Green tick on Test Connection and ability to run a simple query like SELECT 1;.
• Port Forwarding Confirmation: On the bastion, run ss -ltnp | grep 5432 to see the listener on the forwarded port.
• Network Path: From the bastion, try telnet db.internal.local 5432 to confirm reachability.

Common Failure Modes & Recovery

Problem	Likely Cause	Recovery
SSH authentication fails	Wrong password, key not accepted, or key format unsupported by DBeaver.	Verify key permissions, convert key to OpenSSH format with ssh-keygen -p -m PEM -f ~/.ssh/id_rsa if needed, and retry.
Tunnel opens but JDBC test fails	Remote host or port mis‑specified, or firewall blocks the forwarded port.	From the bastion, run nc -zv db.internal.local 5432 to confirm reachability; adjust Remote host/port accordingly.
Connection drops after idle period	SSH server closes idle sessions.	Set Keep‑alive interval to a non‑zero value (e.g., 60) in the SSH tab.
Driver not found	JDBC driver missing or incompatible.	Open the Driver Manager, download the correct driver, and re‑associate it with the connection.

Security Considerations

• Never store plaintext passwords in exported connection files. If you must export, use the --export-credentials=false flag.
• Use key‑based authentication whenever possible; enable agent forwarding only if required.
• Ensure the bastion’s sshd_config restricts port forwarding to trusted users (e.g., AllowTcpForwarding yes for specific users).

Version‑Specific Notes

• DBeaver 23+ includes support for Ed25519 keys; older releases may reject them.
• Check the Help → About DBeaver → Version Details dialog for the exact SSH library version (JSch or Apache MINA).
• Some Enterprise Edition builds disable the Test tunnel configuration button; use the console output for debugging.

Conclusion

By configuring an SSH tunnel in DBeaver, you can safely access databases that are only reachable from a bastion host. The key steps are to correctly set the SSH tab, test both the tunnel and JDBC layers separately, and apply the recovery actions if either layer fails. Once the connection is verified, you can use DBeaver’s full feature set—schema browsing, query execution, and data export—without exposing the database to the public network.