feat: add lazy database connections (#235)

* feat: add lazy database connections

Add `lazy` option to source configuration that defers database connection
until the first query. This avoids unnecessary connection overhead for
remote databases when queries may not occur during a session.

- Add `lazy?: boolean` to SourceConfig type
- Implement lazy connection logic in ConnectorManager with race condition
  protection via pending connection promises
- Update tool handlers to call ensureConnected() before getting connector
- Update dbhub.toml.example and documentation

Closes #234

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

* Update src/connectors/manager.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

dbhub.toml.example

@@ -38,10 +38,11 @@ dsn = "postgres://postgres:postgres@localhost:5432/myapp"
 # dsn = "postgres://dev_user:dev_password@dev-db.internal.company.com:5432/myapp_dev?sslmode=require"
 # connection_timeout = 30
 
-# Production PostgreSQL (behind SSH bastion)
+# Production PostgreSQL (behind SSH bastion, lazy connection)
 # [[sources]]
 # id = "prod_pg"
 # dsn = "postgres://app_user:secure_password@10.0.1.100:5432/myapp_prod?sslmode=require"
+# lazy = true  # Defer connection until first query (avoids startup overhead for remote DBs)
 # connection_timeout = 30
 # # SSH tunnel configuration
 # ssh_host = "bastion.company.com"
@@ -254,6 +255,7 @@ dsn = "postgres://postgres:postgres@localhost:5432/myapp"
 #   id = "unique_id"           # Required: unique identifier
 #   description = "..."        # Optional: human-readable description
 #   dsn = "..."                # Connection string (or use individual params below)
+#   lazy = true                # Defer connection until first query (default: false)
 #
 # DSN Formats:
 #   PostgreSQL:  postgres://user:pass@host:5432/database?sslmode=require

docs/config/toml.mdx

@@ -8,7 +8,7 @@ TOML configuration is the recommended way to configure DBHub for multi-database
 
 TOML configuration enables:
 - **Multi-database support**: Connect to multiple databases from a single DBHub instance
-- **Per-source settings**: Configure timeouts, SSL, and SSH tunnels individually per database
+- **Per-source settings**: Configure timeouts, SSL, SSH tunnels, and lazy connections individually per database
 - **Per-tool settings**: Apply different restrictions (readonly, max_rows) per tool
 - **Custom tools**: Define reusable, parameterized SQL operations as MCP tools
 
@@ -180,6 +180,29 @@ Sources define database connections. Each source represents a database that DBHu
   </Note>
 </ParamField>
 
+### lazy
+
+<ParamField path="lazy" type="boolean" default="false">
+  Defer database connection until the first query. When enabled, the connection is not established at server startup but instead when a tool first accesses this source.
+
+  This is useful for remote databases (e.g., RDS, Cloud SQL) where you want to avoid unnecessary connection overhead if the database may not be queried during a session.
+
+  ```toml
+  [[sources]]
+  id = "production"
+  dsn = "postgres://user:pass@prod-db.example.com:5432/mydb"
+  lazy = true  # Connection deferred until first query
+  ```
+
+  **Startup behavior:**
+  - Without `lazy`: Connection established immediately, errors shown at startup
+  - With `lazy = true`: Source registered but not connected, connection errors appear on first query
+
+  <Note>
+  When a lazy source is accessed for the first time, there will be a brief delay as the connection is established. Connection errors will appear in tool responses rather than at startup.
+  </Note>
+</ParamField>
+
 ### sslmode
 
 <ParamField path="sslmode" type="string">
@@ -473,6 +496,7 @@ Tools define MCP tools (like `execute_sql`) with specific execution settings. To
 [[sources]]
 id = "production"
 dsn = "postgres://user:pass@db.prod.internal:5432/mydb"
+lazy = true  # Defer connection until first query
 connection_timeout = 60
 query_timeout = 30
 sslmode = "require"
@@ -544,6 +568,7 @@ default = 10
 |-------|------|----------|-------------|
 | `id` | string | ✅ | Unique source identifier |
 | `dsn` | string | ✅ | Database connection string |
+| `lazy` | boolean | ❌ | Defer connection until first query (default: `false`) |
 | `connection_timeout` | number | ❌ | Connection timeout (seconds) |
 | `query_timeout` | number | ❌ | Query timeout (seconds) |
 | `sslmode` | string | ❌ | SSL mode: `disable`, `require` |

src/connectors/manager.ts

@@ -20,6 +20,10 @@ export class ConnectorManager {
   private sourceConfigs: Map<string, SourceConfig> = new Map(); // Store original source configs
   private sourceIds: string[] = []; // Ordered list of source IDs (first is default)
 
+  // Lazy connection support
+  private lazySources: Map<string, SourceConfig> = new Map(); // Sources pending lazy connection
+  private pendingConnections: Map<string, Promise<void>> = new Map(); // Prevent race conditions
+
   constructor() {
     if (!managerInstance) {
       managerInstance = this;
@@ -35,12 +39,95 @@ export class ConnectorManager {
       throw new Error("No sources provided");
     }
 
-    console.error(`Connecting to ${sources.length} database source(s)...`);
+    const eagerSources = sources.filter(s => !s.lazy);
+    const lazySources = sources.filter(s => s.lazy);
+
+    if (eagerSources.length > 0) {
+      console.error(`Connecting to ${eagerSources.length} database source(s)...`);
+    }
 
-    // Connect to each source
-    for (const source of sources) {
+    // Connect to eager sources immediately
+    for (const source of eagerSources) {
       await this.connectSource(source);
     }
+
+    // Register lazy sources without connecting
+    for (const source of lazySources) {
+      this.registerLazySource(source);
+    }
+  }
+
+  /**
+   * Register a lazy source without establishing connection
+   * Connection will be established on first use via ensureConnected()
+   */
+  private registerLazySource(source: SourceConfig): void {
+    const sourceId = source.id;
+    const dsn = buildDSNFromSource(source);
+
+    console.error(`  - ${sourceId}: ${redactDSN(dsn)} (lazy, will connect on first use)`);
+
+    // Store config for later connection
+    this.lazySources.set(sourceId, source);
+    this.sourceConfigs.set(sourceId, source);
+    this.sourceIds.push(sourceId);
+  }
+
+  /**
+   * Ensure a source is connected (handles lazy connection on demand)
+   * Safe to call multiple times - uses promise-based deduplication so concurrent calls share the same connection attempt
+   */
+  async ensureConnected(sourceId?: string): Promise<void> {
+    const id = sourceId || this.sourceIds[0];
+
+    // Already connected
+    if (this.connectors.has(id)) {
+      return;
+    }
+
+    // Not a lazy source - must be an error
+    const lazySource = this.lazySources.get(id);
+    if (!lazySource) {
+      if (sourceId) {
+        throw new Error(
+          `Source '${sourceId}' not found. Available sources: ${this.sourceIds.join(", ")}`
+        );
+      } else {
+        throw new Error("No sources configured. Call connectWithSources() first.");
+      }
+    }
+
+    // Check if connection is already in progress (race condition prevention)
+    const pending = this.pendingConnections.get(id);
+    if (pending) {
+      return pending;
+    }
+
+    // Start connection and track the promise
+    const connectionPromise = (async () => {
+      try {
+        console.error(`Lazy connecting to source '${id}'...`);
+        await this.connectSource(lazySource);
+        // Remove from lazy sources after successful connection
+        this.lazySources.delete(id);
+      } finally {
+        // Clean up pending connection tracker
+        this.pendingConnections.delete(id);
+      }
+    })();
+
+    this.pendingConnections.set(id, connectionPromise);
+    return connectionPromise;
+  }
+
+  /**
+   * Static method to ensure a source is connected (for tool handlers)
+   */
+  static async ensureConnected(sourceId?: string): Promise<void> {
+    if (!managerInstance) {
+      throw new Error("ConnectorManager not initialized");
+    }
+    return managerInstance.ensureConnected(sourceId);
   }
 
   /**
@@ -138,7 +225,11 @@ export class ConnectorManager {
 
     // Store connector
     this.connectors.set(sourceId, connector);
-    this.sourceIds.push(sourceId);
+
+    // Only add to sourceIds if not already present (lazy sources are pre-registered)
+    if (!this.sourceIds.includes(sourceId)) {
+      this.sourceIds.push(sourceId);
+    }
 
     // Store source config (for API exposure)
     this.sourceConfigs.set(sourceId, source);
@@ -171,6 +262,8 @@ export class ConnectorManager {
     this.connectors.clear();
     this.sshTunnels.clear();
     this.sourceConfigs.clear();
+    this.lazySources.clear();
+    this.pendingConnections.clear();
     this.sourceIds = [];
   }
 
@@ -242,7 +335,7 @@ export class ConnectorManager {
    * @param sourceId - Source ID. If not provided, returns default (first) source config
    */
   getSourceConfig(sourceId?: string): SourceConfig | null {
-    if (this.connectors.size === 0) {
+    if (this.sourceIds.length === 0) {
       return null;
     }
     const id = sourceId || this.sourceIds[0];

src/tools/custom-tool-handler.ts

@@ -168,37 +168,40 @@ export function createCustomToolHandler(toolConfig: ToolConfig) {
       // 1. Validate arguments against Zod schema
       const validatedArgs = zodSchema.parse(args);
 
-      // 2. Get connector for the specified source
+      // 2. Ensure source is connected (handles lazy connections)
+      await ConnectorManager.ensureConnected(toolConfig.source);
+
+      // 3. Get connector for the specified source
       const connector = ConnectorManager.getCurrentConnector(toolConfig.source);
 
-      // 3. Build execute options from tool configuration
+      // 4. Build execute options from tool configuration
       const executeOptions = {
         readonly: toolConfig.readonly,
         maxRows: toolConfig.max_rows,
       };
 
-      // 4. Check if SQL is allowed based on readonly mode
+      // 5. Check if SQL is allowed based on readonly mode
       const isReadonly = executeOptions.readonly === true;
       if (isReadonly && !isAllowedInReadonlyMode(toolConfig.statement, connector.id)) {
         errorMessage = createReadonlyViolationMessage(toolConfig.name, toolConfig.source, connector.id);
         success = false;
         return createToolErrorResponse(errorMessage, "READONLY_VIOLATION");
       }
 
-      // 5. Map parameters to array format for SQL execution
+      // 6. Map parameters to array format for SQL execution
       paramValues = mapArgumentsToArray(
         toolConfig.parameters,
         validatedArgs
       );
 
-      // 6. Execute SQL with parameters
+      // 7. Execute SQL with parameters
       const result = await connector.executeSQL(
         toolConfig.statement,
         executeOptions,
         paramValues
       );
 
-      // 7. Build response data
+      // 8. Build response data
       const responseData = {
         rows: result.rows,
         count: result.rowCount,

src/tools/execute-sql.ts

@@ -53,6 +53,9 @@ export function createExecuteSqlToolHandler(sourceId?: string) {
     let result: any;
 
     try {
+      // Ensure source is connected (handles lazy connections)
+      await ConnectorManager.ensureConnected(sourceId);
+
       // Get connector for the specified source (or default)
       const connector = ConnectorManager.getCurrentConnector(sourceId);
       const actualSourceId = connector.getId();

src/tools/search-objects.ts

@@ -481,6 +481,9 @@ export function createSearchDatabaseObjectsToolHandler(sourceId?: string) {
     let errorMessage: string | undefined;
 
     try {
+      // Ensure source is connected (handles lazy connections)
+      await ConnectorManager.ensureConnected(sourceId);
+
       const connector = ConnectorManager.getCurrentConnector(sourceId);
 
       // Tool is already registered, so it's enabled (no need to check)

src/types/config.ts

@@ -46,6 +46,7 @@ export interface SourceConfig extends ConnectionParams, SSHConfig {
   connection_timeout?: number; // Connection timeout in seconds
   query_timeout?: number; // Query timeout in seconds (PostgreSQL, MySQL, MariaDB, SQL Server)
   init_script?: string; // Optional SQL script to run on connection (for demo mode or initialization)
+  lazy?: boolean; // Defer connection until first query (default: false)
 }
 
 /**