Architecture Note: Using DataGrip’s SSH Tunnel for Secure Remote Database Access

Requirements

To use DataGrip’s built‑in SSH tunneling you need:

• A reachable SSH server that permits TCP forwarding (AllowTcpForwarding enabled).
• SSH credentials for that server – either a password or a private key file.
• Network connectivity from your workstation to the SSH host (typically port 22).
• The remote database listening on a port reachable from the SSH host (e.g., PostgreSQL on 5432).

Smallest Suitable Design

The minimal configuration consists of four fields in the DataGrip data source dialog:

1. SSH host – hostname or IP of the SSH gateway.
2. SSH port – usually 22.
3. Username – account on the SSH host.
4. Authentication – password or path to a private key file.

DataGrip then opens a local listener on a port you choose (or lets DataGrip pick one) and forwards traffic through the SSH server to the remote database port.

Trust and Data Boundaries

The SSH tunnel creates two distinct trust zones:

• Client ↔ SSH host – you trust the SSH server for authentication and integrity of the forwarded traffic.
• SSH host ↔ Database – the database sees connections originating from localhost on the SSH host, so only the SSH host needs to be allowed to reach the database port.

Thus the database port is not exposed to the broader network; only the SSH host can initiate the forwarded connection.

Operational Checks

After saving the data source, verify the tunnel is active:

• Look for the tunnel icon in the DB console; it should indicate an active forwarded port.
• Run a simple query; successful execution confirms end‑to‑end connectivity.
• From a local terminal, confirm the forwarding socket exists:

# Replace 5432 with the local port you configured
netstat -lnT | grep 5432
# or
lsof -iTCP:5432 -sTCP:LISTEN

Ensure the SSH key file permissions are restrictive (e.g., chmod 600 ~/.ssh/id_rsa) to prevent other users from reading the key.

Failure Modes

Typical ways the tunnel can break:

• SSH authentication failure (wrong password or key).
• Network interruption between client and SSH host causing the SSH process to exit.
• Port conflict on the chosen local forwarding port (another program already bound).
• SSH server reconfiguration that disables AllowTcpForwarding or restricts allowed ports.
• Remote database becomes unreachable from the SSH host.

All of these result in DataGrip reporting a connection loss and the tunnel status changing to disconnected. Manual reconnection or tunnel re‑establishment is required.

Conditions That Would Change the Design

You would reconsider using DataGrip’s SSH tunnel if:

• Latency introduced by the double hop (client → SSH host → database) becomes unacceptable for workloads.
• The SSH host cannot be configured to allow TCP forwarding (policy restriction).
• Native TLS or cloud‑provider IAM authentication is available and offers lower overhead.
• You need to forward multiple heterogeneous services; a dedicated VPN or SSH bastion might scale better.

Concrete Example Configuration

Suppose you want to connect to a PostgreSQL instance running on db.internal.example.com:5432 via an SSH bastion at bastion.example.com.

1. In DataGrip, create a new PostgreSQL data source.
2. Under the SSH/SSL tab, enable "Use SSH tunnel".
3. Fill in:
   • SSH host: bastion.example.com
   • SSH port: 22
   • Username: dbadmin
   • Auth type: Key pair
   • Private key file: ~/.ssh/id_rsa_bastion
4. Set the database host to localhost (because the tunnel makes the DB appear local) and port 5432.
5. Save and test the connection.

Diagnostic Decision Flow

If the connection fails after configuration:

1. Check the SSH tunnel icon – if red, verify SSH credentials and that the bastion is reachable (ssh [contact removed] -i ~/.ssh/id_rsa_bastion).
2. If the icon is green but queries fail, confirm the database is listening on localhost:5432 from the bastion’s perspective (ssh [contact removed] "netstat -lnT | grep 5432").
3. If the local port shows as already in use, choose a different local forwarding port in DataGrip and repeat.

Limitations and Practical Verification

The tunnel adds latency roughly equal to the round‑trip time between your workstation and the SSH host plus the host‑to‑database leg. For latency‑sensitive batch jobs, consider:

• Enabling TLS on the database if supported.
• Using cloud IAM authentication (e.g., AWS IAM DB authentication) to avoid SSH altogether.

To verify latency impact, run a timing query before and after enabling the tunnel and compare execution times; this can be done with the built‑in DB console timing feature.

Rollback Considerations

Establishing an SSH tunnel opens a local listener; closing the data source or disabling the SSH tunnel in DataGrip stops the listener and frees the port. No persistent system state is altered, so a formal rollback procedure is not required beyond disabling the tunnel.