@bytebase/dbhub 0.14.0 → 0.16.0

package/README.md

@@ -23,20 +23,20 @@
             |                  |    |              |    |                  |
             |  VS Code         +--->+              +--->+    MySQL         |
             |                  |    |              |    |                  |
-            |  Other Clients   +--->+              +--->+    MariaDB       |
+            |  Copilot CLI     +--->+              +--->+    MariaDB       |
             |                  |    |              |    |                  |
             |                  |    |              |    |                  |
             +------------------+    +--------------+    +------------------+
                  MCP Clients           MCP Server             Databases
 ```
 
-DBHub is a Minimal Database MCP Server implementing the Model Context Protocol (MCP) server interface. This lightweight gateway allows MCP-compatible clients to connect to and explore different databases:
+DBHub is a zero-dependency, token efficient MCP server implementing the Model Context Protocol (MCP) server interface. This lightweight gateway allows MCP-compatible clients to connect to and explore different databases:
 
-- **Token Efficient**: Just two general MCP tools (execute_sql, search_objects) to minimize context window usage, plus support for custom tools
-- **Multi-Database**: Single interface for PostgreSQL, MySQL, MariaDB, SQL Server, and SQLite
-- **Secure Access**: Read-only mode, SSH tunneling, and SSL/TLS encryption support
-- **Multiple Connections**: Connect to multiple databases simultaneously with TOML configuration
-- **Production-Ready**: Row limiting, lock timeout control, and connection pooling
+- **Local Development First**: Zero dependency, token efficient with just two MCP tools to maximize context window
+- **Multi-Database**: PostgreSQL, MySQL, MariaDB, SQL Server, and SQLite through a single interface
+- **Multi-Connection**: Connect to multiple databases simultaneously with TOML configuration
+- **Guardrails**: Read-only mode, row limiting, and query timeout to prevent runaway operations
+- **Secure Access**: SSH tunneling and SSL/TLS encryption
 
 ## Supported Databases
 
@@ -50,6 +50,12 @@ DBHub implements MCP tools for database operations:
 - **[search_objects](https://dbhub.ai/tools/search-objects)**: Search and explore database schemas, tables, columns, indexes, and procedures with progressive disclosure
 - **[Custom Tools](https://dbhub.ai/tools/custom-tools)**: Define reusable, parameterized SQL operations in your `dbhub.toml` configuration file
 
+## Workbench
+
+DBHub includes a [built-in web interface](https://dbhub.ai/workbench/overview) for interacting with your database tools. It provides a visual way to execute queries, run custom tools, and view request traces without requiring an MCP client.
+
+![workbench](https://raw.githubusercontent.com/bytebase/dbhub/main/docs/images/workbench/workbench.webp)
+
 ## Installation
 
 See the full [Installation Guide](https://dbhub.ai/installation) for detailed instructions.
@@ -80,13 +86,13 @@ npx @bytebase/dbhub@latest --transport http --port 8080 --dsn "postgres://user:p
 npx @bytebase/dbhub@latest --transport http --port 8080 --demo
 ```
 
-See [Server Options](https://dbhub.ai/config/server-options) for all available parameters.
+See [Command-Line Options](https://dbhub.ai/config/command-line) for all available parameters.
 
 ### Multi-Database Setup
 
 Connect to multiple databases simultaneously using TOML configuration files. Perfect for managing production, staging, and development databases from a single DBHub instance.
 
-See [Multi-Database Configuration](https://dbhub.ai/config/multi-database) for complete setup instructions.
+See [Multi-Database Configuration](https://dbhub.ai/config/toml) for complete setup instructions.
 
 ## Development
 

package/dist/{chunk-WGDSRFBW.js → chunk-IBBG4PSO.js}

@@ -1237,11 +1237,6 @@ function validateToolsConfig(tools, sources, configPath) {
           `Configuration file ${configPath}: custom tool '${tool.name}' must have 'description' and 'statement' fields`
         );
       }
-      if (tool.readonly !== void 0 || tool.max_rows !== void 0) {
-        throw new Error(
-          `Configuration file ${configPath}: custom tool '${tool.name}' cannot have readonly or max_rows fields (these are only valid for ${BUILTIN_TOOL_EXECUTE_SQL} tool)`
-        );
-      }
     }
     if (tool.max_rows !== void 0) {
       if (typeof tool.max_rows !== "number" || tool.max_rows <= 0) {
@@ -1250,6 +1245,11 @@ function validateToolsConfig(tools, sources, configPath) {
         );
       }
     }
+    if (tool.readonly !== void 0 && typeof tool.readonly !== "boolean") {
+      throw new Error(
+        `Configuration file ${configPath}: tool '${tool.name}' has invalid readonly. Must be a boolean (true or false).`
+      );
+    }
   }
 }
 function validateSourceConfig(source, configPath) {
@@ -1339,6 +1339,16 @@ function validateSourceConfig(source, configPath) {
       );
     }
   }
+  if (source.readonly !== void 0) {
+    throw new Error(
+      `Configuration file ${configPath}: source '${source.id}' has 'readonly' field, but readonly must be configured per-tool, not per-source. Move 'readonly' to [[tools]] configuration instead.`
+    );
+  }
+  if (source.max_rows !== void 0) {
+    throw new Error(
+      `Configuration file ${configPath}: source '${source.id}' has 'max_rows' field, but max_rows must be configured per-tool, not per-source. Move 'max_rows' to [[tools]] configuration instead.`
+    );
+  }
 }
 function processSourceConfigs(sources, configPath) {
   return sources.map((source) => {
@@ -1441,15 +1451,19 @@ function buildDSNFromSource(source) {
 // src/connectors/manager.ts
 var managerInstance = null;
 var ConnectorManager = class {
-  // Ordered list of source IDs (first is default)
+  // Prevent race conditions
   constructor() {
     // Maps for multi-source support
     this.connectors = /* @__PURE__ */ new Map();
     this.sshTunnels = /* @__PURE__ */ new Map();
-    this.executeOptions = /* @__PURE__ */ new Map();
     this.sourceConfigs = /* @__PURE__ */ new Map();
     // Store original source configs
     this.sourceIds = [];
+    // Ordered list of source IDs (first is default)
+    // Lazy connection support
+    this.lazySources = /* @__PURE__ */ new Map();
+    // Sources pending lazy connection
+    this.pendingConnections = /* @__PURE__ */ new Map();
     if (!managerInstance) {
       managerInstance = this;
     }
@@ -1462,10 +1476,73 @@ var ConnectorManager = class {
     if (sources.length === 0) {
       throw new Error("No sources provided");
     }
-    console.error(`Connecting to ${sources.length} database source(s)...`);
-    for (const source of sources) {
+    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)...`);
+    }
+    for (const source of eagerSources) {
       await this.connectSource(source);
     }
+    for (const source of lazySources) {
+      this.registerLazySource(source);
+    }
+  }
+  /**
+   * Register a lazy source without establishing connection
+   * Connection will be established on first use via ensureConnected()
+   */
+  registerLazySource(source) {
+    const sourceId = source.id;
+    const dsn = buildDSNFromSource(source);
+    console.error(`  - ${sourceId}: ${redactDSN(dsn)} (lazy, will connect on first use)`);
+    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) {
+    const id = sourceId || this.sourceIds[0];
+    if (this.connectors.has(id)) {
+      return;
+    }
+    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.");
+      }
+    }
+    const pending = this.pendingConnections.get(id);
+    if (pending) {
+      return pending;
+    }
+    const connectionPromise = (async () => {
+      try {
+        console.error(`Lazy connecting to source '${id}'...`);
+        await this.connectSource(lazySource);
+        this.lazySources.delete(id);
+      } finally {
+        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) {
+    if (!managerInstance) {
+      throw new Error("ConnectorManager not initialized");
+    }
+    return managerInstance.ensureConnected(sourceId);
   }
   /**
    * Connect to a single source (helper for connectWithSources)
@@ -1531,16 +1608,10 @@ var ConnectorManager = class {
     }
     await connector.connect(actualDSN, source.init_script, config);
     this.connectors.set(sourceId, connector);
-    this.sourceIds.push(sourceId);
-    this.sourceConfigs.set(sourceId, source);
-    const options = {};
-    if (source.max_rows !== void 0) {
-      options.maxRows = source.max_rows;
-    }
-    if (source.readonly !== void 0) {
-      options.readonly = source.readonly;
+    if (!this.sourceIds.includes(sourceId)) {
+      this.sourceIds.push(sourceId);
     }
-    this.executeOptions.set(sourceId, options);
+    this.sourceConfigs.set(sourceId, source);
   }
   /**
    * Close all database connections
@@ -1563,8 +1634,9 @@ var ConnectorManager = class {
     }
     this.connectors.clear();
     this.sshTunnels.clear();
-    this.executeOptions.clear();
     this.sourceConfigs.clear();
+    this.lazySources.clear();
+    this.pendingConnections.clear();
     this.sourceIds = [];
   }
   /**
@@ -1608,25 +1680,6 @@ var ConnectorManager = class {
     }
     return managerInstance.getConnector(sourceId);
   }
-  /**
-   * Get execute options for SQL execution
-   * @param sourceId - Optional source ID. If not provided, returns default options
-   */
-  getExecuteOptions(sourceId) {
-    const id = sourceId || this.sourceIds[0];
-    return this.executeOptions.get(id) || {};
-  }
-  /**
-   * Get the current execute options
-   * This is used by tool handlers
-   * @param sourceId - Optional source ID. If not provided, returns default options
-   */
-  static getCurrentExecuteOptions(sourceId) {
-    if (!managerInstance) {
-      throw new Error("ConnectorManager not initialized");
-    }
-    return managerInstance.getExecuteOptions(sourceId);
-  }
   /**
    * Get all available source IDs
    */
@@ -1645,7 +1698,7 @@ var ConnectorManager = class {
    * @param sourceId - Source ID. If not provided, returns default (first) source config
    */
   getSourceConfig(sourceId) {
-    if (this.connectors.size === 0) {
+    if (this.sourceIds.length === 0) {
       return null;
     }
     const id = sourceId || this.sourceIds[0];