feat: add SSH keepalive configuration options

Add ssh_keepalive_interval and ssh_keepalive_count_max options to prevent
SSH tunnel connections from being dropped due to idle timeouts caused by
NAT gateways, firewalls, or server-side sshd settings.

These options map to the ssh2 library's keepaliveInterval and
keepaliveCountMax settings, allowing users to configure keepalive
behavior per data source via TOML config, CLI arguments, or
environment variables.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: takemi-ohama

dbhub.toml.example

@@ -56,6 +56,8 @@ dsn = "postgres://postgres:postgres@localhost:5432/myapp"
 # ssh_user = "deploy"
 # ssh_key = "~/.ssh/id_ed25519"
 # # ssh_passphrase = "your_key_passphrase"  # If key is encrypted
+# # ssh_keepalive_interval = 60  # Send keepalive every 60 seconds to prevent idle disconnects
+# # ssh_keepalive_count_max = 3  # Disconnect after 3 missed responses
 
 # Production PostgreSQL (multi-hop SSH through multiple jump hosts)
 # [[sources]]
@@ -279,6 +281,8 @@ dsn = "postgres://postgres:postgres@localhost:5432/myapp"
 #   ssh_key (path to private key) OR ssh_password
 #   ssh_passphrase (if key is encrypted)
 #   ssh_proxy_jump (ProxyJump for multi-hop: "jump1.com,user@jump2.com:2222")
+#   ssh_keepalive_interval (seconds between keepalive packets, default: 0 = disabled)
+#   ssh_keepalive_count_max (max missed keepalive responses, default: 3)
 #
 # SSL Mode (for network databases, not SQLite):
 #   sslmode = "disable"   # No SSL

src/config/env.ts

@@ -485,6 +485,24 @@ export function resolveSSHConfig(): { config: SSHTunnelConfig; source: string }
     sources.push("SSH_PROXY_JUMP from environment");
   }
 
+  // SSH Keepalive Interval (optional) - seconds between keepalive packets
+  if (args["ssh-keepalive-interval"]) {
+    config.keepaliveInterval = parseInt(args["ssh-keepalive-interval"], 10);
+    sources.push("ssh-keepalive-interval from command line");
+  } else if (process.env.SSH_KEEPALIVE_INTERVAL) {
+    config.keepaliveInterval = parseInt(process.env.SSH_KEEPALIVE_INTERVAL, 10);
+    sources.push("SSH_KEEPALIVE_INTERVAL from environment");
+  }
+
+  // SSH Keepalive Count Max (optional) - max missed keepalive responses
+  if (args["ssh-keepalive-count-max"]) {
+    config.keepaliveCountMax = parseInt(args["ssh-keepalive-count-max"], 10);
+    sources.push("ssh-keepalive-count-max from command line");
+  } else if (process.env.SSH_KEEPALIVE_COUNT_MAX) {
+    config.keepaliveCountMax = parseInt(process.env.SSH_KEEPALIVE_COUNT_MAX, 10);
+    sources.push("SSH_KEEPALIVE_COUNT_MAX from environment");
+  }
+
   // Validate required fields
   if (!config.host || !config.username) {
     throw new Error("SSH tunnel configuration requires at least --ssh-host and --ssh-user");
@@ -595,6 +613,8 @@ export async function resolveSourceConfigs(): Promise<{ sources: SourceConfig[];
       source.ssh_password = sshResult.config.password;
       source.ssh_key = sshResult.config.privateKey;
       source.ssh_passphrase = sshResult.config.passphrase;
+      source.ssh_keepalive_interval = sshResult.config.keepaliveInterval;
+      source.ssh_keepalive_count_max = sshResult.config.keepaliveCountMax;
     }
 
     // Add init script for demo mode

src/connectors/manager.ts

@@ -157,6 +157,8 @@ export class ConnectorManager {
         privateKey: source.ssh_key,
         passphrase: source.ssh_passphrase,
         proxyJump: source.ssh_proxy_jump,
+        keepaliveInterval: source.ssh_keepalive_interval,
+        keepaliveCountMax: source.ssh_keepalive_count_max,
       };
 
       // Validate SSH auth

src/types/config.ts

@@ -17,6 +17,10 @@ export interface SSHConfig {
    * Comma-separated list of jump hosts: "jump1.example.com,user@jump2.example.com:2222"
    */
   ssh_proxy_jump?: string;
+  /** Interval in seconds between keepalive packets (default: 0 = disabled) */
+  ssh_keepalive_interval?: number;
+  /** Maximum number of missed keepalive responses before disconnecting (default: 3) */
+  ssh_keepalive_count_max?: number;
 }
 
 /**

src/types/ssh.ts

@@ -28,6 +28,12 @@ export interface SSHTunnelConfig {
    * Each host can include optional user and port: "user@host:port"
    */
   proxyJump?: string;
+
+  /** Interval in seconds between keepalive packets sent to the SSH server (default: 0 = disabled) */
+  keepaliveInterval?: number;
+
+  /** Maximum number of missed keepalive responses before disconnecting (default: 3) */
+  keepaliveCountMax?: number;
 }
 
 /**

src/utils/ssh-tunnel.ts

@@ -94,7 +94,9 @@ export class SSHTunnel {
           privateKey,
           targetConfig.passphrase,
           previousStream,
-          `jump host ${i + 1}`
+          `jump host ${i + 1}`,
+          targetConfig.keepaliveInterval,
+          targetConfig.keepaliveCountMax
         );
 
         // Forward to the next host
@@ -126,7 +128,9 @@ export class SSHTunnel {
       privateKey,
       targetConfig.passphrase,
       previousStream,
-      jumpHosts.length > 0 ? 'target host' : undefined
+      jumpHosts.length > 0 ? 'target host' : undefined,
+      targetConfig.keepaliveInterval,
+      targetConfig.keepaliveCountMax
     );
 
     this.sshClients.push(finalClient);
@@ -142,7 +146,9 @@ export class SSHTunnel {
     privateKey: Buffer | undefined,
     passphrase: string | undefined,
     sock: Duplex | undefined,
-    label: string | undefined
+    label: string | undefined,
+    keepaliveInterval?: number,
+    keepaliveCountMax?: number
   ): Promise<Client> {
     return new Promise((resolve, reject) => {
       const client = new Client();
@@ -165,6 +171,10 @@ export class SSHTunnel {
       if (sock) {
         sshConfig.sock = sock;
       }
+      if (keepaliveInterval !== undefined && keepaliveInterval > 0) {
+        sshConfig.keepaliveInterval = keepaliveInterval * 1000; // Convert seconds to milliseconds
+        sshConfig.keepaliveCountMax = keepaliveCountMax ?? 3;
+      }
 
       const onError = (err: Error) => {
         client.removeListener('ready', onReady);