@bytebase/dbhub 0.24.0 → 1.1.0

package/README.md

@@ -32,7 +32,7 @@
 
 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:
 
-- **Local Development First**: Zero dependency, token efficient with just two MCP tools to maximize context window
+- **Local Development First**: Zero dependency, token efficient with a minimal set of 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
@@ -48,6 +48,8 @@ DBHub implements MCP tools for database operations:
 
 - **[execute_sql](https://dbhub.ai/tools/execute-sql)**: Execute SQL queries with transaction support and safety controls
 - **[search_objects](https://dbhub.ai/tools/search-objects)**: Search and explore database schemas, tables, columns, indexes, and procedures with progressive disclosure
+- **[explain_sql](https://dbhub.ai/tools/explain-sql)** (opt-in): Show a query's execution plan without running it
+- **[health_check](https://dbhub.ai/tools/health-check)** (opt-in, PostgreSQL/MySQL/MariaDB/SQL Server for now): Report connection pool state and buffer cache hit ratio
 - **[Custom Tools](https://dbhub.ai/tools/custom-tools)**: Define reusable, parameterized SQL operations in your `dbhub.toml` configuration file
 
 ## Workbench
@@ -58,55 +60,17 @@ DBHub includes a [built-in web interface](https://dbhub.ai/workbench/overview) f
 
 ## Installation
 
-See the full [Installation Guide](https://dbhub.ai/installation) for detailed instructions.
-
-### Quick Start
-
-**Docker:**
-
-```bash
-docker run --rm --init \
-   --name dbhub \
-   --publish 8080:8080 \
-   bytebase/dbhub \
-   --transport http \
-   --port 8080 \
-   --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
-```
-
-**NPM:** (requires Node.js >= 22.5.0)
-
 ```bash
 npx @bytebase/dbhub@latest --transport http --port 8080 --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
 ```
 
-**MCP Bundle (one-click install):**
-
-Download `dbhub-<version>.mcpb` from the [latest release](https://github.com/bytebase/dbhub/releases/latest) and install it in any [MCPB-compatible client](https://github.com/modelcontextprotocol/mcpb) — Claude Desktop (double-click, or drag into Settings → Extensions), Claude Code, or MCP for Windows — then enter your database connection string. The bundle runs locally over stdio, is **read-only by design** (writes are rejected and the database session is set to read-only at the engine level), and needs no remote endpoint or OAuth setup — ideal for giving non-technical teammates curated, read-only database access. Pair it with a least-privilege, read-only database account. See the [MCP Bundle guide](https://dbhub.ai/mcpb) for details and for packaging your own bundle.
-
-**Demo Mode:**
-
-```bash
-npx @bytebase/dbhub@latest --transport http --port 8080 --demo
-```
-
-**Restrict to loopback (recommended for production):**
-
-```bash
-npx @bytebase/dbhub@latest --transport http --host 127.0.0.1 --port 8080 --demo
-```
-
-> The HTTP transport defaults to `--host 0.0.0.0`, exposing DBHub on every network interface. For production, bind to `127.0.0.1` and front DBHub with a reverse proxy (nginx/Caddy) or firewall — DBHub does not authenticate HTTP clients.
->
-> The HTTP transport also has built-in DNS-rebinding protection: it only accepts requests whose `Host` is loopback, this machine's own hostname/IPs, or a name you allow via [`--allowed-hosts`](https://dbhub.ai/config/command-line#allowed-hosts). If a client behind a reverse proxy or custom DNS name gets a `403`, add that hostname with `--allowed-hosts`.
-
-See [Command-Line Options](https://dbhub.ai/config/command-line) for all available parameters.
-
-### Multi-Database Setup
+Also available as:
 
-Connect to multiple databases simultaneously using TOML configuration files. Perfect for managing production, staging, and development databases from a single DBHub instance.
+- [Docker image](https://dbhub.ai/installation#docker)
+- [MCP Bundle](https://dbhub.ai/mcpb) (one-click install, read-only)
+- [Claude Code plugin](https://dbhub.ai/claude-code-plugin)
 
-See [Multi-Database Configuration](https://dbhub.ai/config/toml) for complete setup instructions.
+See the [Installation Guide](https://dbhub.ai/installation) for all options, [Command-Line Options](https://dbhub.ai/config/command-line) for parameters, and [Multi-Database Configuration](https://dbhub.ai/config/toml) for connecting several databases at once.
 
 ## Development
 

package/dist/{chunk-JO7YQPBQ.js → chunk-EPOKWSFC.js}

@@ -52,6 +52,22 @@ var sqlServerPassThroughPattern = new RegExp(
   `\\b(?:${sqlServerPassThroughKeywords.join("|")})\\s*\\(`,
   "i"
 );
+var escapeHatchFunctionKeywords = {
+  mysql: ["load_file", "get_lock", "release_lock", "release_all_locks"],
+  mariadb: ["load_file", "get_lock", "release_lock", "release_all_locks"],
+  postgres: ["pg_read_file", "pg_read_binary_file", "pg_ls_dir"],
+  sqlserver: sqlServerPassThroughKeywords
+};
+var escapeHatchFunctionPatterns = Object.fromEntries(
+  Object.entries(escapeHatchFunctionKeywords).map(([type, keywords]) => [
+    type,
+    new RegExp(`\\b(?:${keywords.join("|")})\\s*\\(`, "i")
+  ])
+);
+function hasEscapeHatchFunction(strippedSQL, connectorType) {
+  const pattern = escapeHatchFunctionPatterns[connectorType];
+  return pattern !== void 0 && pattern.test(strippedSQL);
+}
 var mutatingPatternSqlServer = new RegExp(
   `\\b(?:${[...mutatingKeywords, ...sqlServerDynamicSqlKeywords].join("|")})\\b`,
   "i"
@@ -78,6 +94,10 @@ function isReadOnlySQL(sql, connectorType) {
     connectorType
   );
 }
+function getFirstKeyword(sql, connectorType) {
+  const cleaned = stripCommentsAndStrings(sql, connectorType).trim();
+  return cleaned.match(/\S+/)?.[0]?.toLowerCase() ?? "";
+}
 function checkReadOnly(cleanedSQL, connectorType) {
   if (!cleanedSQL) {
     return false;
@@ -87,7 +107,7 @@ function checkReadOnly(cleanedSQL, connectorType) {
   if (!keywordList.includes(firstWord)) {
     return false;
   }
-  if (connectorType === "sqlserver" && sqlServerPassThroughPattern.test(cleanedSQL)) {
+  if (hasEscapeHatchFunction(cleanedSQL, connectorType)) {
     return false;
   }
   if (firstWord === "with") {
@@ -126,5 +146,7 @@ export {
   sqlServerDynamicSqlPattern,
   sqlServerPassThroughKeywords,
   sqlServerPassThroughPattern,
-  isReadOnlySQL
+  hasEscapeHatchFunction,
+  isReadOnlySQL,
+  getFirstKeyword
 };

package/dist/chunk-FU2ZJE4E.js

@@ -0,0 +1,16 @@
+// src/connectors/health-check-utils.ts
+function toNullableNumber(value) {
+  return value === null || value === void 0 ? null : Number(value);
+}
+function computeHitRatioPct(logicalReads, physicalReads) {
+  if (!Number.isFinite(logicalReads) || !Number.isFinite(physicalReads) || logicalReads === 0) {
+    return null;
+  }
+  const pct = Math.round((logicalReads - physicalReads) / logicalReads * 1e4) / 100;
+  return Math.min(100, Math.max(0, pct));
+}
+
+export {
+  toNullableNumber,
+  computeHitRatioPct
+};

package/dist/{chunk-MQR6VX5F.js → chunk-GSSLHJB6.js}

@@ -13,10 +13,17 @@ import {
 // src/tools/builtin-tools.ts
 var BUILTIN_TOOL_EXECUTE_SQL = "execute_sql";
 var BUILTIN_TOOL_SEARCH_OBJECTS = "search_objects";
+var BUILTIN_TOOL_EXPLAIN_SQL = "explain_sql";
+var BUILTIN_TOOL_HEALTH_CHECK = "health_check";
 var BUILTIN_TOOLS = [
   BUILTIN_TOOL_EXECUTE_SQL,
   BUILTIN_TOOL_SEARCH_OBJECTS
 ];
+var ALL_BUILTIN_TOOL_NAMES = [
+  ...BUILTIN_TOOLS,
+  BUILTIN_TOOL_EXPLAIN_SQL,
+  BUILTIN_TOOL_HEALTH_CHECK
+];
 
 // src/utils/ssh-tunnel.ts
 import { Client } from "ssh2";
@@ -1130,7 +1137,7 @@ function validateToolsConfig(tools, sources, configPath) {
         `Configuration file ${configPath}: tool '${tool.name}' references unknown source '${tool.source}'`
       );
     }
-    const isBuiltin = BUILTIN_TOOLS.includes(tool.name);
+    const isBuiltin = ALL_BUILTIN_TOOL_NAMES.includes(tool.name);
     const isExecuteSql = tool.name === BUILTIN_TOOL_EXECUTE_SQL;
     if (isBuiltin) {
       if (tool.description || tool.statement || tool.parameters) {
@@ -2278,7 +2285,7 @@ var ToolRegistry = class {
    * Check if a tool name is a built-in tool
    */
   isBuiltinTool(toolName) {
-    return BUILTIN_TOOLS.includes(toolName);
+    return ALL_BUILTIN_TOOL_NAMES.includes(toolName);
   }
   /**
    * Validate a custom tool parameter definition
@@ -2350,10 +2357,10 @@ var ToolRegistry = class {
         `Tool '${toolConfig.name}' references unknown source '${toolConfig.source}'. Available sources: ${availableSources.join(", ")}`
       );
     }
-    for (const builtinName of BUILTIN_TOOLS) {
+    for (const builtinName of ALL_BUILTIN_TOOL_NAMES) {
       if (toolConfig.name === builtinName || toolConfig.name.startsWith(`${builtinName}_`)) {
         throw new Error(
-          `Tool name '${toolConfig.name}' conflicts with built-in tool naming pattern. Custom tools cannot use names starting with: ${BUILTIN_TOOLS.join(", ")}`
+          `Tool name '${toolConfig.name}' conflicts with built-in tool naming pattern. Custom tools cannot use names starting with: ${ALL_BUILTIN_TOOL_NAMES.join(", ")}`
         );
       }
     }
@@ -2488,6 +2495,8 @@ export {
   resolveSourceConfigs,
   BUILTIN_TOOL_EXECUTE_SQL,
   BUILTIN_TOOL_SEARCH_OBJECTS,
+  BUILTIN_TOOL_EXPLAIN_SQL,
+  BUILTIN_TOOL_HEALTH_CHECK,
   loadTomlConfig,
   resolveTomlConfigPath,
   classifyConnectionError,

package/dist/chunk-NIILHXTG.js

@@ -0,0 +1,190 @@
+import {
+  computeHitRatioPct,
+  toNullableNumber
+} from "./chunk-FU2ZJE4E.js";
+import {
+  obfuscateDSNPassword
+} from "./chunk-JEZZN2YZ.js";
+
+// src/connectors/mysql-family-health-check.ts
+async function getMySQLFamilyHealthCheck(query) {
+  const [processlistRows, maxConnRows, bufferPoolRows, trxOutcome] = await Promise.all([
+    query(`
+      SELECT
+        COUNT(*) AS total,
+        SUM(CASE WHEN COMMAND != 'Sleep' THEN 1 ELSE 0 END) AS active,
+        SUM(CASE WHEN COMMAND = 'Sleep' THEN 1 ELSE 0 END) AS idle,
+        MAX(CASE WHEN COMMAND != 'Sleep' THEN TIME ELSE NULL END) AS longest_active_query_seconds
+      FROM information_schema.PROCESSLIST
+      WHERE ID <> CONNECTION_ID()
+    `),
+    query(`SHOW VARIABLES LIKE 'max_connections'`),
+    query(`
+      SHOW GLOBAL STATUS WHERE Variable_name IN ('Innodb_buffer_pool_read_requests', 'Innodb_buffer_pool_reads')
+    `),
+    // Joining PROCESSLIST against INNODB_TRX to detect idle-in-transaction
+    // sessions requires the PROCESS privilege - unlike a plain PROCESSLIST
+    // select, which silently narrows to the caller's own session instead of
+    // erroring. Run concurrently with the other queries above, but resolve
+    // rather than reject on failure so it degrades instead of failing the
+    // whole health check.
+    query(`
+      SELECT
+        COUNT(*) AS idle_in_transaction,
+        MAX(TIMESTAMPDIFF(SECOND, t.trx_started, NOW())) AS longest_idle_in_transaction_seconds
+      FROM information_schema.INNODB_TRX t
+      JOIN information_schema.PROCESSLIST p ON p.ID = t.trx_mysql_thread_id
+      WHERE p.COMMAND = 'Sleep'
+    `).then(
+      (rows) => ({ ok: true, rows }),
+      () => ({ ok: false })
+    )
+  ]);
+  const notes = [];
+  let idleInTransaction = 0;
+  let longestIdleInTransactionSeconds = null;
+  if (trxOutcome.ok) {
+    idleInTransaction = Number(trxOutcome.rows[0].idle_in_transaction);
+    longestIdleInTransactionSeconds = toNullableNumber(trxOutcome.rows[0].longest_idle_in_transaction_seconds);
+  } else {
+    notes.push(
+      "Connected user lacks the PROCESS privilege: PROCESSLIST visibility is restricted to the connecting user's own sessions, and this diagnostic session is excluded from the count, so connection counts and active-query duration may under-report (down to 0). Idle-in-transaction detection is unavailable."
+    );
+  }
+  const proc = processlistRows[0];
+  const bufferPoolStats = Object.fromEntries(bufferPoolRows.map((row) => [row.Variable_name, row.Value]));
+  const readRequests = Number(bufferPoolStats.Innodb_buffer_pool_read_requests ?? 0);
+  const reads = Number(bufferPoolStats.Innodb_buffer_pool_reads ?? 0);
+  return {
+    connections: {
+      total: Number(proc.total),
+      active: Number(proc.active),
+      idle: Number(proc.idle),
+      idleInTransaction,
+      // MySQL/MariaDB's InnoDB has no equivalent of Postgres's "idle in
+      // transaction (aborted)" state - a failed statement doesn't leave the
+      // session's transaction in a distinct aborted-but-open state the way
+      // Postgres does - so idleInTransactionAborted is left undefined.
+      maxConnections: maxConnRows.length > 0 ? Number(maxConnRows[0].Value) : null,
+      longestIdleInTransactionSeconds,
+      longestActiveQuerySeconds: toNullableNumber(proc.longest_active_query_seconds)
+    },
+    bufferCache: {
+      hitRatioPct: computeHitRatioPct(readRequests, reads),
+      blocksHit: readRequests - reads,
+      blocksRead: reads
+    },
+    ...notes.length > 0 ? { notes } : {}
+  };
+}
+
+// src/utils/dsn-database.ts
+var MissingDatabaseError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MissingDatabaseError";
+  }
+};
+function requireDatabaseInDSN(database, dsn, label) {
+  if (database) {
+    return;
+  }
+  throw new MissingDatabaseError(
+    `${label} DSN must name a database.
+Provided: ${obfuscateDSNPassword(dsn)}
+Add the database to the DSN, e.g. ...:3306/mydb
+To work with several databases, define one [[sources]] entry per database in a TOML config file: https://dbhub.ai/config/toml`
+  );
+}
+
+// src/utils/multi-statement-result-parser.ts
+function isMetadataObject(element) {
+  if (!element || typeof element !== "object" || Array.isArray(element)) {
+    return false;
+  }
+  return "affectedRows" in element || "insertId" in element || "fieldCount" in element || "warningStatus" in element;
+}
+function isMultiStatementResult(results) {
+  if (!Array.isArray(results) || results.length === 0) {
+    return false;
+  }
+  const firstElement = results[0];
+  return isMetadataObject(firstElement) || Array.isArray(firstElement);
+}
+function extractRowsFromMultiStatement(results) {
+  if (!Array.isArray(results)) {
+    return [];
+  }
+  const allRows = [];
+  for (const result of results) {
+    if (Array.isArray(result)) {
+      allRows.push(...result);
+    }
+  }
+  return allRows;
+}
+function extractAffectedRows(results) {
+  if (isMetadataObject(results)) {
+    return results.affectedRows || 0;
+  }
+  if (!Array.isArray(results)) {
+    return 0;
+  }
+  if (isMultiStatementResult(results)) {
+    let totalAffected = 0;
+    for (const result of results) {
+      if (isMetadataObject(result)) {
+        totalAffected += result.affectedRows || 0;
+      } else if (Array.isArray(result)) {
+        totalAffected += result.length;
+      }
+    }
+    return totalAffected;
+  }
+  return results.length;
+}
+function parseQueryResults(results) {
+  if (!Array.isArray(results)) {
+    return [];
+  }
+  if (isMultiStatementResult(results)) {
+    return extractRowsFromMultiStatement(results);
+  }
+  return results;
+}
+
+// src/utils/readonly-transaction.ts
+async function withReadOnlyTransaction(conn, readonly, supportsReadOnlyTransaction, execute) {
+  if (!readonly) {
+    return execute();
+  }
+  try {
+    await conn.query(
+      supportsReadOnlyTransaction ? "START TRANSACTION READ ONLY" : "START TRANSACTION"
+    );
+    const result = await execute();
+    await conn.query(supportsReadOnlyTransaction ? "COMMIT" : "ROLLBACK");
+    return result;
+  } catch (error) {
+    try {
+      await conn.query("ROLLBACK");
+    } catch {
+    }
+    throw error;
+  }
+}
+
+// src/utils/server-flavor.ts
+function isTiDBVersion(version) {
+  return typeof version === "string" && /tidb/i.test(version);
+}
+
+export {
+  getMySQLFamilyHealthCheck,
+  MissingDatabaseError,
+  requireDatabaseInDSN,
+  extractAffectedRows,
+  parseQueryResults,
+  withReadOnlyTransaction,
+  isTiDBVersion
+};

package/dist/{chunk-D2BIPC7V.js → chunk-S2V6RZ3C.js}

@@ -66,7 +66,8 @@ var SQLRowLimiter = class {
       const trimmed = sql.trim();
       const hasSemicolon = trimmed.endsWith(";");
       const sqlWithoutSemicolon = hasSemicolon ? trimmed.slice(0, -1) : trimmed;
-      return `${sqlWithoutSemicolon} LIMIT ${maxRows}${hasSemicolon ? ";" : ""}`;
+      return `${sqlWithoutSemicolon}
+LIMIT ${maxRows}${hasSemicolon ? ";" : ""}`;
     }
   }
   /**
@@ -107,7 +108,8 @@ var SQLRowLimiter = class {
       const trimmed = sql.trim();
       const hasSemicolon = trimmed.endsWith(";");
       const sqlWithoutSemicolon = hasSemicolon ? trimmed.slice(0, -1) : trimmed;
-      return `SELECT * FROM (${sqlWithoutSemicolon}) AS subq LIMIT ${maxRows}${hasSemicolon ? ";" : ""}`;
+      return `SELECT * FROM (${sqlWithoutSemicolon}
+) AS subq LIMIT ${maxRows}${hasSemicolon ? ";" : ""}`;
     }
     return this.applyLimitToQuery(sql, maxRows);
   }