SSH Configuration

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: 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.

DBeaver allows the use of Jump servers, also known as Gateway hosts. This feature is essential when the direct access to a target machine is not possible from your local machine, and a gateway server is required for connection.

To add a jump server:

1. Ensure Use SSH Tunnel is checked.
2. Expand the Jump servers group.
3. Specify your target in the Settings section.
4. Click on the Create new jump host button to add your first jump server configuration.

Repeat step 3 for each additional jump host you need to add, configuring each one within the Settings section.

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.

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 default 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 (random 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 change 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.

By default, DBeaver shares SSH tunnels across connections when the same SSH settings are used. This is particularly useful when connecting to several databases on the same remote server, as it avoids the need to establish a separate SSH tunnel for each connection.

To view the active SSH tunnels and the databases utilizing a shared tunnel, use the SSH tunnel explorer. This feature provides a comprehensive overview of your SSH tunnel usage, including detailed information on each tunnel and the databases it serves. Here is how to access SSH tunnel explorer:

1. Navigate to Window -> Show View -> Other...
2. In the window that appears, expand the Database category.
3. Select SSH tunnel explorer and click Open.

In the SSH tunnel explorer view, you will find information about each active tunnel. This includes:

DBeaver shares SSH tunnels across connections if SSH settings are identical. The application compares the following parameters to determine if the SSH settings match:

• Hostname: The address of the SSH server.
• Host port: The port number used for the SSH connection.
• Username: The username required for SSH authentication.

Depending on the authentication method selected, DBeaver also compares:

• For password authentication:
  • Password: The SSH account password.
• For public key authentication:
  • Private Key: The file path to the SSH private key.
  • Passphrase: The passphrase for decrypting the private key, if set.
• For agent authentication:
  • Agents: DBeaver treats all agent authentication configurations as identical, ignoring specific agent settings and focusing only on the method's selection.