feat: implement connection_timeout (#124)

Author: tianzhou

dbhub.toml.example

@@ -7,87 +7,101 @@
 
 ## Example 1: PostgreSQL with DSN (recommended)
 [[sources]]
-id = "prod_pg"
-dsn = "postgres://user:password@localhost:5432/production?sslmode=require"
-readonly = false
-max_rows = 1000
+id = "prod_pg"  # Required: Unique identifier
+dsn = "postgres://user:password@localhost:5432/production?sslmode=require"  # Required: Connection string
+readonly = false  # Optional: Limit to read-only operations (default: false)
+max_rows = 1000  # Optional: Maximum rows to return per query (default: unlimited)
+connection_timeout = 30  # Optional: Connection timeout in seconds (default: driver-specific)
 
 ## Example 2: MySQL with individual parameters
 [[sources]]
-id = "staging_mysql"
-type = "mysql"
-host = "localhost"
-port = 3306
-database = "staging"
-user = "root"
-password = "secret"
-readonly = false
-max_rows = 500
+id = "staging_mysql"  # Required: Unique identifier
+type = "mysql"  # Required when using individual parameters (not DSN)
+host = "localhost"  # Required when using individual parameters
+port = 3306  # Optional: Uses default if not specified (MySQL default: 3306)
+database = "staging"  # Required: Database name
+user = "root"  # Required: Database username
+password = "secret"  # Required: Database password
+readonly = false  # Optional: Limit to read-only operations (default: false)
+max_rows = 500  # Optional: Maximum rows to return per query (default: unlimited)
+connection_timeout = 60  # Optional: Connection timeout in seconds (useful for high-latency connections)
 
 ## Example 3: MariaDB with SSH tunnel
 [[sources]]
-id = "remote_mariadb"
-dsn = "mariadb://dbuser:[email protected]:3306/mydb"
-ssh_host = "bastion.example.com"
-ssh_port = 22
-ssh_user = "ubuntu"
-ssh_key = "~/.ssh/id_rsa"
-# ssh_passphrase = "optional_key_passphrase"
-# ssh_password = "optional_ssh_password"  # Use instead of ssh_key for password auth
+id = "remote_mariadb"  # Required: Unique identifier
+dsn = "mariadb://dbuser:[email protected]:3306/mydb"  # Required: Connection string (target DB behind SSH tunnel)
+ssh_host = "bastion.example.com"  # Optional: SSH server hostname (required if using SSH tunnel)
+ssh_port = 22  # Optional: SSH server port (default: 22)
+ssh_user = "ubuntu"  # Optional: SSH username (required if using SSH tunnel)
+ssh_key = "~/.ssh/id_rsa"  # Optional: Path to private key file (use ssh_key OR ssh_password)
+# ssh_passphrase = "key_passphrase"  # Optional: Passphrase for encrypted private key
+# ssh_password = "ssh_password"  # Optional: SSH password (use instead of ssh_key for password auth)
 
-## Example 4: SQL Server
+## Example 4: SQL Server with timeouts
 [[sources]]
-id = "analytics_sqlserver"
-type = "sqlserver"
-host = "sqlserver.example.com"
-port = 1433
-database = "analytics"
-user = "sa"
-password = "YourStrong@Passw0rd"
-max_rows = 2000
-# instanceName = "optional_instance_name"
+id = "analytics_sqlserver"  # Required: Unique identifier
+type = "sqlserver"  # Required when using individual parameters
+host = "sqlserver.example.com"  # Required when using individual parameters
+port = 1433  # Optional: Uses default if not specified (SQL Server default: 1433)
+database = "analytics"  # Required: Database name
+user = "sa"  # Required: Database username
+password = "YourStrong@Passw0rd"  # Required: Database password
+max_rows = 2000  # Optional: Maximum rows to return per query (default: unlimited)
+connection_timeout = 30  # Optional: Connection establishment timeout in seconds (default: 15s)
+request_timeout = 120    # Optional: Query execution timeout in seconds (SQL Server only, default: 15s)
+# instanceName = "INSTANCE1"  # Optional: SQL Server named instance (e.g., SERVER\INSTANCE1)
 
 ## Example 5: SQLite local file
 [[sources]]
-id = "local_sqlite"
-type = "sqlite"
-database = "/path/to/database.db"
-readonly = true
+id = "local_sqlite"  # Required: Unique identifier
+type = "sqlite"  # Required when using individual parameters
+database = "/path/to/database.db"  # Required: Path to SQLite database file
+readonly = true  # Optional: Limit to read-only operations (default: false)
 
 ## Example 6: SQLite in-memory (for testing)
 [[sources]]
-id = "test_db"
-dsn = "sqlite:///:memory:"
+id = "test_db"  # Required: Unique identifier
+dsn = "sqlite:///:memory:"  # Required: Connection string (in-memory database)
 
 # Connection Parameters Reference:
 # -------------------------------
-# Required for each source:
-#   - id: Unique identifier for this database source
 #
-# Connection options (choose one):
-#   Option A: Full DSN string
-#     - dsn: Complete connection string (e.g., "postgres://user:pass@host:port/db")
+# REQUIRED FIELDS:
+# ----------------
+#   - id: Unique identifier for this database source (string)
 #
-#   Option B: Individual parameters
-#     - type: Database type (postgres, mysql, mariadb, sqlserver, sqlite)
-#     - host: Database host (not needed for sqlite)
-#     - port: Database port (optional, uses default if not specified)
-#     - database: Database name or file path (for sqlite)
-#     - user: Database username (not needed for sqlite)
-#     - password: Database password (not needed for sqlite)
-#     - instanceName: SQL Server named instance (optional, for sqlserver only)
+#   AND one of:
+#     Option A: DSN (connection string)
+#       - dsn: Complete connection string (e.g., "postgres://user:pass@host:port/db")
 #
-# Execution options (optional):
+#     Option B: Individual connection parameters
+#       - type: Database type (postgres, mysql, mariadb, sqlserver, sqlite) [REQUIRED]
+#       - database: Database name or file path [REQUIRED]
+#       For network databases (postgres, mysql, mariadb, sqlserver):
+#         - host: Database host [REQUIRED]
+#         - user: Database username [REQUIRED]
+#         - password: Database password [REQUIRED]
+#       For SQLite: only database path is needed
+#
+# OPTIONAL FIELDS:
+# ----------------
+# Connection parameters:
+#   - port: Database port (default: 5432 for postgres, 3306 for mysql/mariadb, 1433 for sqlserver)
+#   - instanceName: SQL Server named instance (sqlserver only, e.g., "INSTANCE1")
+#
+# Execution options:
 #   - readonly: Limit to read-only operations (default: false)
-#   - max_rows: Maximum rows to return per query (default: unlimited)
+#   - max_rows: Maximum rows to return per query (default: unlimited, e.g., 1000)
+#   - connection_timeout: Connection timeout in seconds (default: driver-specific, e.g., 30, 60)
+#   - request_timeout: Query execution timeout in seconds (SQL Server only, default: 15, e.g., 120)
 #
-# SSH tunnel options (optional):
+# SSH tunnel options (all optional, but if using SSH tunnel, ssh_host, ssh_user required):
 #   - ssh_host: SSH server hostname or IP
 #   - ssh_port: SSH server port (default: 22)
 #   - ssh_user: SSH username
-#   - ssh_password: SSH password (for password authentication)
-#   - ssh_key: Path to private key file (for key-based authentication)
-#   - ssh_passphrase: Passphrase for encrypted private key (optional)
+#   - ssh_key: Path to private key file (use ssh_key OR ssh_password, not both)
+#   - ssh_password: SSH password (use instead of ssh_key for password authentication)
+#   - ssh_passphrase: Passphrase for encrypted private key
 
 # Default Port Numbers:
 # - PostgreSQL: 5432

src/config/__tests__/toml-loader.test.ts

@@ -233,6 +233,134 @@ ssh_port = 99999
 
       expect(() => loadTomlConfig()).toThrow('Configuration file specified by --config flag not found');
     });
+
+    describe('connection_timeout validation', () => {
+      it('should accept valid connection_timeout', () => {
+        const tomlContent = `
+[[sources]]
+id = "test_db"
+dsn = "postgres://user:pass@localhost:5432/testdb"
+connection_timeout = 60
+`;
+        fs.writeFileSync(path.join(tempDir, 'dbhub.toml'), tomlContent);
+
+        const result = loadTomlConfig();
+
+        expect(result).toBeTruthy();
+        expect(result?.sources[0].connection_timeout).toBe(60);
+      });
+
+      it('should throw error for negative connection_timeout', () => {
+        const tomlContent = `
+[[sources]]
+id = "test_db"
+dsn = "postgres://user:pass@localhost:5432/testdb"
+connection_timeout = -30
+`;
+        fs.writeFileSync(path.join(tempDir, 'dbhub.toml'), tomlContent);
+
+        expect(() => loadTomlConfig()).toThrow('invalid connection_timeout');
+      });
+
+      it('should throw error for zero connection_timeout', () => {
+        const tomlContent = `
+[[sources]]
+id = "test_db"
+dsn = "postgres://user:pass@localhost:5432/testdb"
+connection_timeout = 0
+`;
+        fs.writeFileSync(path.join(tempDir, 'dbhub.toml'), tomlContent);
+
+        expect(() => loadTomlConfig()).toThrow('invalid connection_timeout');
+      });
+
+      it('should accept large connection_timeout values', () => {
+        const tomlContent = `
+[[sources]]
+id = "test_db"
+dsn = "postgres://user:pass@localhost:5432/testdb"
+connection_timeout = 300
+`;
+        fs.writeFileSync(path.join(tempDir, 'dbhub.toml'), tomlContent);
+
+        const result = loadTomlConfig();
+
+        expect(result).toBeTruthy();
+        expect(result?.sources[0].connection_timeout).toBe(300);
+      });
+
+      it('should work without connection_timeout (optional field)', () => {
+        const tomlContent = `
+[[sources]]
+id = "test_db"
+dsn = "postgres://user:pass@localhost:5432/testdb"
+`;
+        fs.writeFileSync(path.join(tempDir, 'dbhub.toml'), tomlContent);
+
+        const result = loadTomlConfig();
+
+        expect(result).toBeTruthy();
+        expect(result?.sources[0].connection_timeout).toBeUndefined();
+      });
+    });
+
+    describe('request_timeout validation', () => {
+      it('should accept valid request_timeout', () => {
+        const tomlContent = `
+[[sources]]
+id = "test_db"
+dsn = "sqlserver://user:pass@localhost:1433/testdb"
+request_timeout = 120
+`;
+        fs.writeFileSync(path.join(tempDir, 'dbhub.toml'), tomlContent);
+
+        const result = loadTomlConfig();
+
+        expect(result).toBeTruthy();
+        expect(result?.sources[0].request_timeout).toBe(120);
+      });
+
+      it('should throw error for negative request_timeout', () => {
+        const tomlContent = `
+[[sources]]
+id = "test_db"
+dsn = "sqlserver://user:pass@localhost:1433/testdb"
+request_timeout = -60
+`;
+        fs.writeFileSync(path.join(tempDir, 'dbhub.toml'), tomlContent);
+
+        expect(() => loadTomlConfig()).toThrow('invalid request_timeout');
+      });
+
+      it('should throw error for zero request_timeout', () => {
+        const tomlContent = `
+[[sources]]
+id = "test_db"
+dsn = "sqlserver://user:pass@localhost:1433/testdb"
+request_timeout = 0
+`;
+        fs.writeFileSync(path.join(tempDir, 'dbhub.toml'), tomlContent);
+
+        expect(() => loadTomlConfig()).toThrow('invalid request_timeout');
+      });
+
+      it('should accept both connection_timeout and request_timeout', () => {
+        const tomlContent = `
+[[sources]]
+id = "test_db"
+dsn = "sqlserver://user:pass@localhost:1433/testdb"
+connection_timeout = 30
+request_timeout = 120
+`;
+        fs.writeFileSync(path.join(tempDir, 'dbhub.toml'), tomlContent);
+
+        const result = loadTomlConfig();
+
+        expect(result).toBeTruthy();
+        expect(result?.sources[0].connection_timeout).toBe(30);
+        expect(result?.sources[0].request_timeout).toBe(120);
+      });
+    });
   });
 
   describe('buildDSNFromSource', () => {

src/config/toml-loader.ts

@@ -161,6 +161,26 @@ function validateSourceConfig(source: SourceConfig, configPath: string): void {
     }
   }
 
+  // Validate connection_timeout if provided
+  if (source.connection_timeout !== undefined) {
+    if (typeof source.connection_timeout !== "number" || source.connection_timeout <= 0) {
+      throw new Error(
+        `Configuration file ${configPath}: source '${source.id}' has invalid connection_timeout. ` +
+          `Must be a positive number (in seconds).`
+      );
+    }
+  }
+
+  // Validate request_timeout if provided
+  if (source.request_timeout !== undefined) {
+    if (typeof source.request_timeout !== "number" || source.request_timeout <= 0) {
+      throw new Error(
+        `Configuration file ${configPath}: source '${source.id}' has invalid request_timeout. ` +
+          `Must be a positive number (in seconds).`
+      );
+    }
+  }
+
   // Validate SSH port if provided
   if (source.ssh_port !== undefined) {
     if (

src/connectors/interface.ts

@@ -42,6 +42,20 @@ export interface StoredProcedure {
 export interface ExecuteOptions {
   /** Maximum number of rows to return (applied via database-native LIMIT) */
   maxRows?: number;
+  /** Restrict to read-only SQL operations */
+  readonly?: boolean;
+}
+
+/**
+ * Configuration options for database connections
+ * Different databases may use different subset of these options
+ */
+export interface ConnectorConfig {
+  /** Connection timeout in seconds (PostgreSQL, MySQL, MariaDB, SQL Server) */
+  connectionTimeoutSeconds?: number;
+  /** Request/query timeout in seconds (SQL Server only) */
+  requestTimeoutSeconds?: number;
+  // Future database-specific options can be added here as optional fields
 }
 
 /**
@@ -51,13 +65,15 @@ export interface ExecuteOptions {
 export interface DSNParser {
   /**
    * Parse a connection string into connector-specific configuration
+   * @param dsn - Database connection string
+   * @param config - Optional database-specific configuration options
    * Example DSN formats:
    * - PostgreSQL: "postgres://user:password@localhost:5432/dbname?sslmode=disable"
    * - MariaDB: "mariadb://user:password@localhost:3306/dbname"
    * - MySQL: "mysql://user:password@localhost:3306/dbname"
    * - SQLite: "sqlite:///path/to/database.db" or "sqlite:///:memory:"
    */
-  parse(dsn: string): Promise<any>;
+  parse(dsn: string, config?: ConnectorConfig): Promise<any>;
 
   /**
    * Generate a sample DSN string for this connector type
@@ -83,8 +99,8 @@ export interface Connector {
   /** Create a new instance of this connector (for multi-source support) - optional, only implemented for tested connectors */
   clone?(): Connector;
 
-  /** Connect to the database using DSN, with optional init script */
-  connect(dsn: string, initScript?: string): Promise<void>;
+  /** Connect to the database using DSN, with optional init script and database-specific configuration */
+  connect(dsn: string, initScript?: string, config?: ConnectorConfig): Promise<void>;
 
   /** Close the connection */
   disconnect(): Promise<void>;

src/connectors/manager.ts

@@ -1,4 +1,4 @@
-import { Connector, ConnectorType, ConnectorRegistry, ExecuteOptions } from "./interface.js";
+import { Connector, ConnectorType, ConnectorRegistry, ExecuteOptions, ConnectorConfig } from "./interface.js";
 import { SSHTunnel } from "../utils/ssh-tunnel.js";
 import { resolveSSHConfig, resolveMaxRows } from "../config/env.js";
 import type { SSHTunnelConfig } from "../types/ssh.js";
@@ -192,8 +192,17 @@ export class ConnectorManager {
     // Other databases will reuse the singleton instance (not recommended for multi-source)
     const connector = connectorPrototype.clone ? connectorPrototype.clone() : connectorPrototype;
 
-    // Connect to the database
-    await connector.connect(actualDSN);
+    // Build config for database-specific options
+    const config: ConnectorConfig = {};
+    if (source.connection_timeout !== undefined) {
+      config.connectionTimeoutSeconds = source.connection_timeout;
+    }
+    if (connector.id === 'sqlserver' && source.request_timeout !== undefined) {
+      config.requestTimeoutSeconds = source.request_timeout;
+    }
+
+    // Connect to the database with config
+    await connector.connect(actualDSN, undefined, config);
 
     // Store connector
     this.connectors.set(sourceId, connector);