@bytebase/dbhub 1.1.0 → 1.2.1

package/README.md

@@ -1,5 +1,15 @@
 > [!NOTE]  
-> Brought to you by [Bytebase](https://www.bytebase.com/), open-source database DevSecOps platform.
+> Brought to you by [Bytebase](https://www.bytebase.com/), open-source database governance platform.
+
+<p align="center">
+ <a href="https://www.star-history.com/bytebase/dbhub">
+  <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=bytebase/dbhub&type=trending&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=bytebase/dbhub&type=trending" />
+   <img alt="GitHub Trending Repository of the Day" src="https://api.star-history.com/badge?repo=bytebase/dbhub&type=trending" />
+  </picture>
+ </a>
+</p>
 
 <p align="center">
 <a href="https://dbhub.ai/" target="_blank">
@@ -30,14 +40,33 @@
                  MCP Clients           MCP Server             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:
+DBHub is a minimal MCP server: token-efficient, zero-dependency, and just two tools by default with opt-in extras. This lightweight gateway allows MCP-compatible clients to connect to and explore different databases:
 
-- **Local Development First**: Zero dependency, token efficient with a minimal set of MCP tools to maximize context window
+- **Minimal**: 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
 - **Secure Access**: SSH tunneling and SSL/TLS encryption
 
+> DBHub is the official example in the [Claude Code docs](https://code.claude.com/docs/en/mcp#example-query-your-postgresql-database) for connecting to PostgreSQL via MCP.
+
+## Token Efficiency
+
+DBHub loads just 2 tools by default at **1.4k tokens** — 13-14x fewer than alternatives — keeping the context window open for your actual work.
+
+| MCP Server | Default Config | Default Tools |
+|------------|---------------|--------------|
+| **DBHub** | **1.4k** | 2 (`execute_sql`, `search_objects`) |
+| MCP Toolbox | 19.0k | 28 |
+| Supabase MCP | 19.3k | all |
+
+## Use Cases
+
+- **Local Development**: Schema exploration, query validation, and data debugging with Claude Code, VS Code, Cursor, etc.
+- **Non-Technical Access**: Expose curated, read-only views to non-technical staff via Claude Desktop, VS Code, Cursor, etc.
+- **Multi-Database Consolidation**: Replace separate MCP servers for each database with a single DBHub process
+- **Production Troubleshooting**: Read-only diagnostics with guardrails against runaway queries
+
 ## Supported Databases
 
 PostgreSQL, MySQL, SQL Server, MariaDB, and SQLite.
@@ -49,7 +78,7 @@ 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
+- **[health_check](https://dbhub.ai/tools/health-check)** (opt-in): 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

package/dist/{chunk-GSSLHJB6.js → chunk-2DFLBX4D.js}

@@ -8,7 +8,7 @@ import {
   getDefaultPortForType,
   parseConnectionInfoFromDSN,
   stripCommentsAndStrings
-} from "./chunk-JEZZN2YZ.js";
+} from "./chunk-MF6LSVWK.js";
 
 // src/tools/builtin-tools.ts
 var BUILTIN_TOOL_EXECUTE_SQL = "execute_sql";
@@ -805,6 +805,21 @@ function resolveAllowedHosts() {
 function splitHostList(value) {
   return value.split(",").map((h) => h.trim()).filter((h) => h.length > 0);
 }
+function resolveAuthTokens() {
+  const args = parseCommandLineArgs();
+  const cliValue = requireFlagValue("auth-token", args, "secret1,secret2");
+  if (cliValue !== void 0) {
+    return { tokens: splitTokenList(cliValue), source: "command line argument" };
+  }
+  const envValue = process.env.DBHUB_AUTH_TOKEN?.trim();
+  if (envValue) {
+    return { tokens: splitTokenList(envValue), source: "environment variable" };
+  }
+  return { tokens: [], source: "default" };
+}
+function splitTokenList(value) {
+  return value.split(",").map((t) => t.trim()).filter((t) => t.length > 0);
+}
 function redactDSN(dsn) {
   try {
     const url = new URL(dsn);
@@ -1292,6 +1307,18 @@ function validateSourceConfig(source, configPath) {
       );
     }
   }
+  if (source.aws_profile !== void 0) {
+    if (typeof source.aws_profile !== "string" || source.aws_profile.trim().length === 0) {
+      throw new Error(
+        `Configuration file ${configPath}: source '${source.id}' has invalid aws_profile. Must be a non-empty string.`
+      );
+    }
+    if (source.aws_iam_auth !== true) {
+      throw new Error(
+        `Configuration file ${configPath}: source '${source.id}' aws_profile requires aws_iam_auth = true.`
+      );
+    }
+  }
   if (source.aws_iam_auth === true) {
     const validIamTypes = ["postgres", "mysql", "mariadb"];
     if (!source.type || !validIamTypes.includes(source.type)) {
@@ -1662,12 +1689,17 @@ async function generateRdsAuthToken(params) {
     }
     throw error;
   }
-  const signer = new Signer({
+  const signerConfig = {
     hostname: params.hostname,
     port: params.port,
     username: params.username,
     region: params.region
-  });
+  };
+  if (params.profile) {
+    const { fromIni } = await import("@aws-sdk/credential-providers");
+    signerConfig.credentials = fromIni({ profile: params.profile });
+  }
+  const signer = new Signer(signerConfig);
   return signer.getAuthToken();
 }
 
@@ -2143,7 +2175,8 @@ var ConnectorManager = class {
       hostname,
       port,
       username,
-      region: source.aws_region
+      region: source.aws_region,
+      profile: source.aws_profile
     });
     const queryParams = new Map(parsed.searchParams);
     const currentSslMode = queryParams.get("sslmode");
@@ -2492,6 +2525,7 @@ export {
   resolvePort,
   resolveHost,
   resolveAllowedHosts,
+  resolveAuthTokens,
   resolveSourceConfigs,
   BUILTIN_TOOL_EXECUTE_SQL,
   BUILTIN_TOOL_SEARCH_OBJECTS,

package/dist/chunk-6QETXS44.js

@@ -0,0 +1,254 @@
+import {
+  blankCommentsAndStrings,
+  stripCommentsAndStrings
+} from "./chunk-MF6LSVWK.js";
+
+// src/utils/sql-row-limiter.ts
+var SQLRowLimiter = class {
+  /**
+   * Check if a SQL statement is a SELECT query that can benefit from row limiting
+   * Only handles SELECT queries
+   */
+  static isSelectQuery(sql) {
+    const trimmed = sql.trim().toLowerCase();
+    return trimmed.startsWith("select");
+  }
+  /**
+   * Check if a SQL statement already has a LIMIT clause.
+   * Strips comments and string literals first to avoid false positives.
+   */
+  static hasLimitClause(sql) {
+    const cleanedSQL = stripCommentsAndStrings(sql);
+    const limitRegex = /\blimit\s+(?:\d+|\$\d+|\?|@p\d+)/i;
+    return limitRegex.test(cleanedSQL);
+  }
+  /**
+   * Check if a SQL statement already has a TOP clause (SQL Server).
+   * Strips comments and string literals first to avoid false positives.
+   */
+  static hasTopClause(sql) {
+    const cleanedSQL = stripCommentsAndStrings(sql);
+    const topRegex = /\bselect\s+top\s+\d+/i;
+    return topRegex.test(cleanedSQL);
+  }
+  /**
+   * Extract existing LIMIT value from SQL if present.
+   * Strips comments and string literals first to avoid false positives.
+   */
+  static extractLimitValue(sql) {
+    const cleanedSQL = stripCommentsAndStrings(sql);
+    const limitMatch = cleanedSQL.match(/\blimit\s+(\d+)/i);
+    if (limitMatch) {
+      return parseInt(limitMatch[1], 10);
+    }
+    return null;
+  }
+  /**
+   * Extract existing TOP value from SQL if present (SQL Server).
+   * Strips comments and string literals first to avoid false positives.
+   */
+  static extractTopValue(sql) {
+    const cleanedSQL = stripCommentsAndStrings(sql);
+    const topMatch = cleanedSQL.match(/\bselect\s+top\s+(\d+)/i);
+    if (topMatch) {
+      return parseInt(topMatch[1], 10);
+    }
+    return null;
+  }
+  /**
+   * Add or modify LIMIT clause in a SQL statement
+   */
+  static applyLimitToQuery(sql, maxRows) {
+    const existingLimit = this.extractLimitValue(sql);
+    if (existingLimit !== null) {
+      const effectiveLimit = Math.min(existingLimit, maxRows);
+      return sql.replace(/\blimit\s+\d+/i, `LIMIT ${effectiveLimit}`);
+    } else {
+      const trimmed = sql.trim();
+      const hasSemicolon = trimmed.endsWith(";");
+      const sqlWithoutSemicolon = hasSemicolon ? trimmed.slice(0, -1) : trimmed;
+      return `${sqlWithoutSemicolon}
+LIMIT ${maxRows}${hasSemicolon ? ";" : ""}`;
+    }
+  }
+  /**
+   * Scan blanked (comment/string-free, length-preserving) SQL for parenthesis
+   * depth, invoking onMatch for every regex hit at depth 0 (i.e. not nested
+   * inside a subquery, function call, or window OVER clause).
+   */
+  static scanTopLevel(blankedSQL, regex, onMatch) {
+    let depth = 0;
+    let m;
+    while ((m = regex.exec(blankedSQL)) !== null) {
+      const token = m[0];
+      if (token === "(") {
+        depth++;
+      } else if (token === ")") {
+        depth--;
+      } else if (depth === 0) {
+        onMatch(m);
+      }
+    }
+  }
+  /**
+   * Check if a SQL statement combines multiple SELECTs with a set operator
+   * (UNION [ALL], INTERSECT, EXCEPT) at the top level — i.e. not nested
+   * inside a subquery already wrapped in parentheses. Strips comments and
+   * string literals first to avoid false positives.
+   */
+  static hasSetOperator(sql) {
+    const blankedSQL = blankCommentsAndStrings(sql, "sqlserver");
+    let found = false;
+    this.scanTopLevel(blankedSQL, /\(|\)|\bunion\b|\bintersect\b|\bexcept\b/gi, () => {
+      found = true;
+    });
+    return found;
+  }
+  /**
+   * Find the start index of a top-level trailing ORDER BY clause (not one
+   * nested inside a subquery or a window function's OVER (...) clause).
+   * Returns -1 if none exists. Operates on the original (non-blanked) SQL
+   * length, since blankCommentsAndStrings preserves length/position.
+   */
+  static findTopLevelOrderByIndex(sql) {
+    const blankedSQL = blankCommentsAndStrings(sql, "sqlserver");
+    let lastIndex = -1;
+    this.scanTopLevel(blankedSQL, /\(|\)|\border\s+by\b/gi, (m) => {
+      lastIndex = m.index;
+    });
+    return lastIndex;
+  }
+  /**
+   * Add or modify TOP clause in a SQL statement (SQL Server)
+   */
+  static applyTopToQuery(sql, maxRows) {
+    if (this.hasSetOperator(sql)) {
+      const trimmed = sql.trim();
+      const hasSemicolon = trimmed.endsWith(";");
+      const sqlWithoutSemicolon = hasSemicolon ? trimmed.slice(0, -1) : trimmed;
+      const orderByIndex = this.findTopLevelOrderByIndex(sqlWithoutSemicolon);
+      if (orderByIndex !== -1) {
+        const innerSql = sqlWithoutSemicolon.slice(0, orderByIndex).trimEnd();
+        const orderByClause = sqlWithoutSemicolon.slice(orderByIndex).trim();
+        return `SELECT TOP ${maxRows} * FROM (${innerSql}
+) AS subq ${orderByClause}${hasSemicolon ? ";" : ""}`;
+      }
+      return `SELECT TOP ${maxRows} * FROM (${sqlWithoutSemicolon}
+) AS subq${hasSemicolon ? ";" : ""}`;
+    }
+    const existingTop = this.extractTopValue(sql);
+    if (existingTop !== null) {
+      const effectiveTop = Math.min(existingTop, maxRows);
+      return sql.replace(/\bselect\s+top\s+\d+/i, `SELECT TOP ${effectiveTop}`);
+    }
+    return sql.replace(/\bselect\s+/i, `SELECT TOP ${maxRows} `);
+  }
+  /**
+   * Check if a LIMIT clause uses a parameter placeholder (not a literal number).
+   * Strips comments and string literals first to avoid false positives.
+   */
+  static hasParameterizedLimit(sql) {
+    const cleanedSQL = stripCommentsAndStrings(sql);
+    const parameterizedLimitRegex = /\blimit\s+(?:\$\d+|\?|@p\d+)/i;
+    return parameterizedLimitRegex.test(cleanedSQL);
+  }
+  /**
+   * Apply maxRows limit to a SELECT query only
+   *
+   * This method is used by PostgreSQL, MySQL, MariaDB, and SQLite connectors which all support
+   * the LIMIT clause syntax. SQL Server uses applyMaxRowsForSQLServer() instead with TOP syntax.
+   *
+   * For parameterized LIMIT clauses (e.g., LIMIT $1 or LIMIT ?), we wrap the query in a subquery
+   * to enforce max_rows as a hard cap, since the parameter value is not known until runtime.
+   */
+  static applyMaxRows(sql, maxRows) {
+    if (!maxRows || !this.isSelectQuery(sql)) {
+      return sql;
+    }
+    if (this.hasParameterizedLimit(sql)) {
+      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 this.applyLimitToQuery(sql, maxRows);
+  }
+  /**
+   * Apply maxRows limit to a SELECT query using SQL Server TOP syntax
+   */
+  static applyMaxRowsForSQLServer(sql, maxRows) {
+    if (!maxRows || !this.isSelectQuery(sql)) {
+      return sql;
+    }
+    return this.applyTopToQuery(sql, maxRows);
+  }
+  /**
+   * Like applyMaxRows, but requests one probe row (maxRows + 1) whenever the
+   * cap is the binding constraint, so callers can detect truncation exactly
+   * instead of guessing from `rowCount === maxRows` (which a table with
+   * exactly maxRows rows also produces).
+   *
+   * `probeApplied` is false when the cap cannot fire: no maxRows, not a
+   * SELECT, or the query's own literal LIMIT is already within the cap (the
+   * user asked for fewer rows than the cap — that is their limit, not
+   * truncation).
+   */
+  static applyMaxRowsWithTruncationProbe(sql, maxRows) {
+    if (!maxRows || !this.isSelectQuery(sql)) {
+      return { sql, probeApplied: false };
+    }
+    if (!this.hasParameterizedLimit(sql)) {
+      const existingLimit = this.extractLimitValue(sql);
+      if (existingLimit !== null && existingLimit <= maxRows) {
+        return { sql, probeApplied: false };
+      }
+    }
+    return { sql: this.applyMaxRows(sql, maxRows + 1), probeApplied: true };
+  }
+  /**
+   * SQL Server variant of applyMaxRowsWithTruncationProbe, using TOP syntax.
+   * A set-operator statement is always wrapped (any TOP on an individual
+   * branch caps only that branch, not the combined output), so the probe
+   * applies there regardless of branch-level TOPs.
+   */
+  static applyMaxRowsForSQLServerWithTruncationProbe(sql, maxRows) {
+    if (!maxRows || !this.isSelectQuery(sql)) {
+      return { sql, probeApplied: false };
+    }
+    if (!this.hasSetOperator(sql)) {
+      const existingTop = this.extractTopValue(sql);
+      if (existingTop !== null && existingTop <= maxRows) {
+        return { sql, probeApplied: false };
+      }
+    }
+    return { sql: this.applyMaxRowsForSQLServer(sql, maxRows + 1), probeApplied: true };
+  }
+  /**
+   * Post-process a result set produced by a truncation-probe rewrite: when
+   * the probe row came back (more than maxRows rows), drop it, clamp the
+   * count to maxRows, and mark the set truncated so consumers can tell a
+   * capped result from a complete one.
+   */
+  static flagTruncation(resultSet, maxRows, probeApplied) {
+    if (!probeApplied || !maxRows || resultSet.rows.length <= maxRows) {
+      return;
+    }
+    resultSet.rows = resultSet.rows.slice(0, maxRows);
+    resultSet.rowCount = maxRows;
+    resultSet.truncated = true;
+  }
+};
+
+// src/utils/resource-cleanup.ts
+async function closeQuietly(close) {
+  try {
+    await close();
+  } catch {
+  }
+}
+
+export {
+  SQLRowLimiter,
+  closeQuietly
+};

package/dist/{chunk-NIILHXTG.js → chunk-A4TSDCPY.js}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-FU2ZJE4E.js";
 import {
   obfuscateDSNPassword
-} from "./chunk-JEZZN2YZ.js";
+} from "./chunk-MF6LSVWK.js";
 
 // src/connectors/mysql-family-health-check.ts
 async function getMySQLFamilyHealthCheck(query) {
@@ -111,49 +111,36 @@ function isMultiStatementResult(results) {
   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) {
+function buildResultSetsFromMultiStatement(results, statementTexts) {
+  const sql = statementTexts?.length === results.length ? statementTexts : void 0;
+  return results.map((result, index) => {
     if (Array.isArray(result)) {
-      allRows.push(...result);
+      return { sql: sql?.[index], rows: result, rowCount: result.length };
     }
-  }
-  return allRows;
+    if (isMetadataObject(result)) {
+      return { sql: sql?.[index], rows: [], rowCount: result.affectedRows || 0 };
+    }
+    return { sql: sql?.[index], rows: [], rowCount: 0 };
+  });
 }
-function extractAffectedRows(results) {
+function parseQueryResultSets(results, statementTexts) {
+  const singleStatementSql = statementTexts?.length === 1 ? statementTexts[0] : void 0;
   if (isMetadataObject(results)) {
-    return results.affectedRows || 0;
+    return [{ sql: singleStatementSql, rows: [], rowCount: results.affectedRows || 0 }];
   }
   if (!Array.isArray(results)) {
-    return 0;
+    return [{ sql: singleStatementSql, rows: [], rowCount: 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 buildResultSetsFromMultiStatement(results, statementTexts);
   }
-  return results.length;
-}
-function parseQueryResults(results) {
-  if (!Array.isArray(results)) {
-    return [];
-  }
-  if (isMultiStatementResult(results)) {
-    return extractRowsFromMultiStatement(results);
-  }
-  return results;
+  return [{ sql: singleStatementSql, rows: results, rowCount: results.length }];
 }
 
 // src/utils/readonly-transaction.ts
+function isClientSideTimeout(error) {
+  return typeof error === "object" && error !== null && error.code === "PROTOCOL_SEQUENCE_TIMEOUT";
+}
 async function withReadOnlyTransaction(conn, readonly, supportsReadOnlyTransaction, execute) {
   if (!readonly) {
     return execute();
@@ -166,9 +153,11 @@ async function withReadOnlyTransaction(conn, readonly, supportsReadOnlyTransacti
     await conn.query(supportsReadOnlyTransaction ? "COMMIT" : "ROLLBACK");
     return result;
   } catch (error) {
-    try {
-      await conn.query("ROLLBACK");
-    } catch {
+    if (!isClientSideTimeout(error)) {
+      try {
+        await conn.query("ROLLBACK");
+      } catch {
+      }
     }
     throw error;
   }
@@ -183,8 +172,8 @@ export {
   getMySQLFamilyHealthCheck,
   MissingDatabaseError,
   requireDatabaseInDSN,
-  extractAffectedRows,
-  parseQueryResults,
+  parseQueryResultSets,
+  isClientSideTimeout,
   withReadOnlyTransaction,
   isTiDBVersion
 };

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

@@ -1,6 +1,6 @@
 import {
   stripCommentsAndStrings
-} from "./chunk-JEZZN2YZ.js";
+} from "./chunk-MF6LSVWK.js";
 
 // src/utils/allowed-keywords.ts
 var allowedKeywords = {

package/dist/{chunk-JEZZN2YZ.js → chunk-MF6LSVWK.js}

@@ -91,7 +91,9 @@ var SafeURL = class {
           }
         });
       }
-      const atIndex = urlString.indexOf("@");
+      const pathStart = urlString.indexOf("/");
+      const authorityEnd = pathStart === -1 ? urlString.length : pathStart;
+      const atIndex = urlString.lastIndexOf("@", authorityEnd - 1);
       if (atIndex !== -1) {
         const auth = urlString.substring(0, atIndex);
         urlString = urlString.substring(atIndex + 1);
@@ -462,6 +464,21 @@ function stripCommentsAndStrings(sql, dialect) {
   }
   return parts.join("");
 }
+function blankCommentsAndStrings(sql, dialect) {
+  const scanToken = getScanner(dialect);
+  let result = "";
+  let i = 0;
+  while (i < sql.length) {
+    const token = scanToken(sql, i);
+    if (token.type === TokenType.Plain) {
+      result += sql[i];
+    } else {
+      result += " ".repeat(token.end - i);
+    }
+    i = token.end;
+  }
+  return result;
+}
 function splitSQLStatements(sql, dialect) {
   const scanToken = getScanner(dialect);
   const statements = [];
@@ -495,5 +512,6 @@ export {
   getDatabaseTypeFromDSN,
   getDefaultPortForType,
   stripCommentsAndStrings,
+  blankCommentsAndStrings,
   splitSQLStatements
 };