SSH Configuration - bobbyiliev/dbeaver GitHub Wiki

Sometimes the database cannot be accessed directly, in such cases you can use the SSH tunnel. The SSH or Secure Shell is a network communication protocol that allows two computers to communicate and encrypts the shared data.

DBeaver supports the following SSH authentication methods:

• Username/password
• Public key authentication
• Agent authentication

Available agent authentication implementations:

• pageant (Windows only)
• ssh-agent

Note that you have to run the agent first before connecting to the database in DBeaver.

SSH can either be configured individually for each connection in Connection settings ⇒ SSH¹ or as a network profile which can be selected from the drop-down menu² on the same page mentioned earlier:

In order to use SSH, you have to enable it first. After that, configure it for your needs, then click on Test tunnel configuration to test whether all parameters are valid or not.

It is often required to set the hostname to localhost in Connection settings ⇒ Main. SSH establishes a connection between two machines, authenticating each side to the other, and passing commands and output back and forth. After connecting to remote machine, all commands you execute are executed on that remote machine, so by having the host set to localhost you are opening a connection to the database on this remote machine, not on your local machine, and just redirect I/O to the latter.

Gateway host, sometimes known as jump host, is used in situations when you cannot access a particular machine directly from your local machine, but it is possible to use a gateway server.

Just like SSH configuration, you have to enable it first. Gateway has the same configuration as for regular SSH tunnel:

Imagine you have the following situation: your database is located on remote machine with IP address 100.100.100.100 and which is accessible through SSH. You cannot access this IP directly from your machine because of your network settings or firewall, but you can access other machines with the IP address 200.200.200.200 through SSH and which is able to access the desired remote machine. You will need to specify 100.100.100.100 as a host in regular SSH configuration and 200.200.200.200 as a host in a gateway configuration to achieve such a "connection order": localhost → 200.200.200.200 → 100.100.100.100.

Jump servers are only available with Jsch implementation. See information below.

1. Optional port forwarding configuration, see information at below.
2. Keep-alive interval. Can be used to "ping" a remote machine to make sure that the SSH connection is still alive.
3. Connection timeout. If the destination SSH machine is quite slow and the connection takes ages to complete, you can adjust the value of this parameter.

Port forwarding is used to expose some socket sitting on a remote port to your local port, allowing you to communicate with it. After the SSH connection to the remote machine is established, you now need to connect to the database on that machine. Now you need to pass the port on which the database is listening to from that remote machine to your local machine. This is when port forwarding becomes handy.

By default, it randomly chooses the local port and forwards it to the destination port set in Connection settings ⇒ Main

It is not usually required to change this configuration, but it can be useful e.g. when you want to use a particular local port.

By defaul DBeaver opens random local port and forwards it to a target database port. It then implicitly replaces port configured in the connection with this random port.
So technically DBeaver will connect to something like localhost:45678 (radnom port on localhost) instead of database.server.domain:5432 (default PostgreSQL server port).
But if you use URL instead of manual connection configuration then you connect to jdbc:postgresql://database.server.domain/postgresql. DBeaver cannot replace port number automatically because you can use any type of sophisticated URLs. DBeaver just don't know how to chnge this URL.

If you use URL connection then you must configure port forwarding manually. In the Advanced Settings set both Local Port and Remote Port to 5432 (database server port, 5432 is the default value for PostgreSQL). It will work in most cases.
But it will fail if you have PostgreSQL server on your local machine because port 5432 is already occupied. In this case you can use any random port number for Loca Port (e.g. 15432). Use the same 5432 for Remote Port because it is real port number for remote PostgreSQL server.