SSH tunnels

DBCode supports two types of tunnels for connecting to databases that aren’t directly accessible:

• SSH Tunnels: Traditional secure shell tunnels that forward traffic through an SSH server
• Command Tunnels: Local proxy processes that handle authentication and connection forwarding (e.g., Google Cloud SQL Auth Proxy, AWS SSM, kubectl port-forward)

Once configured, tunnels can be selected when creating or editing database connections.

SSH Tunnels

SSH tunnels create a secure, encrypted connection through an intermediate SSH server to reach your database.

Automatic Discovery

DBCode can automatically discover SSH tunnel configurations from your system’s SSH config file.

If you have existing configurations, they will be automatically detected and displayed in the Tunnels section of the DBCode Explorer with a compass icon (🧭)

Manual Configuration

If you prefer to manually create SSH tunnel configurations, follow the steps below. Manual configurations allow for flexible authentication options, including username/password, SSH agent, or key-based authentication.

Add

Click the + icon in the Tunnels section of the DBCode Explorer

Configure

• Tunnel name: Enter the name for the tunnel.
• Type: Select SSH Tunnel.
• Host: Enter the hostname or IP address of the remote server, and the port for the SSH connection (default 22).
• Username: Enter the username for the SSH connection.
• Authentication Type:
  • Password: Provide the password associated with the username.
  • Key File: Select your private key file, and enter its password if the key is encrypted.
  • SSH Agent: Use the SSH agent running on your system to manage keys.

Save

Save the newly created SSH tunnel configuration by clicking the Save button.

Command Tunnels

Command tunnels spawn a local proxy process that handles authentication and connection forwarding. This is useful for cloud database services that provide their own authentication proxies.

Common Use Cases

• Google Cloud SQL: Use cloud-sql-auth-proxy for IAM-based authentication to Cloud SQL instances
• Google AlloyDB: Use alloydb-auth-proxy for connecting to AlloyDB with IAM authentication
• AWS SSM: Use AWS Systems Manager Session Manager for secure port forwarding to RDS instances
• Kubernetes: Use kubectl port-forward to connect to databases running in Kubernetes clusters

Creating a Command Tunnel

1. Click the + icon in the Tunnels section of the DBCode Explorer
2. Select Command Tunnel as the type
3. Configure the tunnel settings:

• Tunnel name: A descriptive name for the tunnel
• Command: The executable to run (e.g., cloud-sql-auth-proxy, kubectl). Select Use preset… to pick a preset for a common tool instead of entering the details manually
• Arguments: Command arguments with variable substitution support
• Ready Pattern: Optional regex pattern to detect when the proxy is ready
• Timeout: Seconds to wait for the proxy to become ready (default: 30)

Variable Substitution

Arguments support the following variables that are replaced at runtime:

Variable	Description	Example
{localPort}	Auto-assigned local port	54321
{remoteHost}	Database host from connection	my-db.example.com
{remotePort}	Database port from connection	5432
{database}	Database name from connection	mydb

Important: Your arguments must include {localPort} so DBCode knows which port to connect to after the proxy starts. DBCode assigns an available port, substitutes it into your arguments, starts the proxy, then connects to that port.

Example Configurations

Google Cloud SQL Auth Proxy:

Command: cloud-sql-auth-proxy
Arguments: my-project:us-central1:my-instance --port={localPort}

kubectl port-forward:

Command: kubectl
Arguments: port-forward svc/my-postgres {localPort}:{remotePort} -n my-namespace

AWS SSM Port Forward:

Command: aws
Arguments: ssm start-session --target i-1234567890abcdef0 --document-name AWS-StartPortForwardingSessionToRemoteHost --parameters host={remoteHost},portNumber={remotePort},localPortNumber={localPort}

Using Tunnels

Once you have a tunnel configured (SSH or Command), you can use it when connecting to your databases.

To use a tunnel for a database connection, create a new connection or edit an existing one, then select the tunnel from the Tunnel dropdown list.

Databases with multiple ports

Some databases need more than one port: RabbitMQ has its management API, Apache Pinot its broker, Weaviate its gRPC endpoint. SSH tunnels forward every port the database needs automatically, so these connections work over a tunnel with no extra configuration. Command tunnels forward a single port only; use an SSH tunnel for multi-port databases.

Active Tunnels

When a tunnel is in use, it will show the databases using the tunnel and the IP addresses and ports being mapped for each database.

Automatic Reconnection

If a tunnel drops, for example when the SSH server restarts, DBCode reconnects it automatically: up to 5 attempts over about 25 seconds with increasing delays. A progress notification shows each attempt and offers Cancel if you know the server is not coming back. After a reconnect, every connection sharing the tunnel is restored to its own database, and multi-port databases get all of their ports forwarded again.

Tunnel Logs

Each tunnel has its own output channel for viewing logs. This is useful for diagnosing connection issues, seeing authentication messages, or debugging command tunnel configuration.

To view tunnel logs:

1. Right-click on a tunnel in the Tunnels section
2. Click View Tunnel Logs
3. The Output panel will open showing the tunnel’s dedicated log channel

Alternatively, click the View Logs icon in the tunnel’s inline actions.

The output channel captures stdout and stderr from the tunnel process, including:

• Connection status messages
• Authentication progress (for command tunnels like cloud-sql-auth-proxy)
• Error messages and warnings
• Port forwarding details