@bytebase/dbhub 1.2.0 → 1.2.2

package/README.md

@@ -1,6 +1,16 @@
 > [!NOTE]  
 > 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">
 <picture>
@@ -30,14 +40,33 @@
                  MCP Clients           MCP Server             Databases
 ```
 
-DBHub is a token efficient, zero-dependency 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.

package/dist/{chunk-RSB7DPO2.js → chunk-6QETXS44.js}

@@ -1,7 +1,7 @@
 import {
   blankCommentsAndStrings,
   stripCommentsAndStrings
-} from "./chunk-WIQ4DWGY.js";
+} from "./chunk-MF6LSVWK.js";
 
 // src/utils/sql-row-limiter.ts
 var SQLRowLimiter = class {
@@ -183,6 +183,61 @@ LIMIT ${maxRows}${hasSemicolon ? ";" : ""}`;
     }
     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

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

@@ -4,7 +4,7 @@ import {
 } from "./chunk-FU2ZJE4E.js";
 import {
   obfuscateDSNPassword
-} from "./chunk-WIQ4DWGY.js";
+} from "./chunk-MF6LSVWK.js";
 
 // src/connectors/mysql-family-health-check.ts
 async function getMySQLFamilyHealthCheck(query) {

package/dist/{chunk-CUBIR72I.js → chunk-F5TPYAVO.js}

@@ -8,7 +8,7 @@ import {
   getDefaultPortForType,
   parseConnectionInfoFromDSN,
   stripCommentsAndStrings
-} from "./chunk-WIQ4DWGY.js";
+} from "./chunk-MF6LSVWK.js";
 
 // src/tools/builtin-tools.ts
 var BUILTIN_TOOL_EXECUTE_SQL = "execute_sql";
@@ -1307,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)) {
@@ -1484,6 +1496,20 @@ function validateSourceConfig(source, configPath) {
     );
   }
 }
+function resolveSqliteDatabasePath(database, configPath) {
+  if (database === ":memory:") {
+    return database;
+  }
+  const expanded = expandHomeDir(database);
+  const absolute = path2.isAbsolute(expanded) ? expanded : path2.resolve(path2.dirname(configPath), expanded);
+  return absolute.replace(/\\/g, "/");
+}
+function buildSqliteDSN(database) {
+  if (database === ":memory:") {
+    return "sqlite:///:memory:";
+  }
+  return `sqlite://${database.startsWith("/") ? database : `/${database}`}`;
+}
 function processSourceConfigs(sources, configPath) {
   return sources.map((source) => {
     const processed = { ...source };
@@ -1494,7 +1520,7 @@ function processSourceConfigs(sources, configPath) {
       processed.sslrootcert = expandHomeDir(processed.sslrootcert);
     }
     if (processed.type === "sqlite" && processed.database) {
-      processed.database = expandHomeDir(processed.database);
+      processed.database = resolveSqliteDatabasePath(processed.database, configPath);
     }
     if (processed.dsn && processed.dsn.startsWith("sqlite:///~")) {
       processed.dsn = `sqlite:///${expandHomeDir(processed.dsn.substring(11))}`;
@@ -1617,7 +1643,7 @@ function buildDSNFromSource(source) {
         `Source '${source.id}': 'database' field is required for SQLite`
       );
     }
-    return `sqlite:///${source.database}`;
+    return buildSqliteDSN(source.database);
   }
   const isAwsIamPasswordless = source.aws_iam_auth === true && ["postgres", "mysql", "mariadb"].includes(source.type);
   const passwordRequired = source.authentication !== "azure-active-directory-access-token" && !isAwsIamPasswordless;
@@ -1677,12 +1703,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();
 }
 
@@ -2158,7 +2189,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");

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

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

package/dist/{chunk-WIQ4DWGY.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);

package/dist/index.js

@@ -18,14 +18,14 @@ import {
   resolveSourceConfigs,
   resolveTomlConfigPath,
   resolveTransport
-} from "./chunk-CUBIR72I.js";
+} from "./chunk-F5TPYAVO.js";
 import {
   allowedKeywords,
   getFirstKeyword,
   hasEscapeHatchFunction,
   isReadOnlySQL,
   sqlServerDynamicSqlPattern
-} from "./chunk-PBN2UXB5.js";
+} from "./chunk-IQRBLAB4.js";
 import {
   loadConnectors
 } from "./chunk-WVVMH6FJ.js";
@@ -39,7 +39,7 @@ import {
   parseConnectionInfoFromDSN,
   splitSQLStatements,
   stripCommentsAndStrings
-} from "./chunk-WIQ4DWGY.js";
+} from "./chunk-MF6LSVWK.js";
 
 // src/server.ts
 import { McpServer, createMcpHandler } from "@modelcontextprotocol/server";
@@ -224,7 +224,11 @@ function toStatementsPayload(resultSets) {
   return resultSets.map((set) => ({
     sql: set.sql,
     rows: set.rows,
-    count: set.rowCount
+    count: set.rowCount,
+    // Only present when a max_rows cap actually cut off rows, so consumers
+    // can tell a capped result from a table with exactly max_rows rows
+    // (and complete results don't pay the extra tokens).
+    ...set.truncated ? { truncated: true } : {}
   }));
 }
 function resolveTrackedToolName(sourceId, baseName) {
@@ -1008,7 +1012,7 @@ function getExecuteSqlMetadata(sourceId) {
     maxRows: toolConfig?.max_rows
   };
   const readonlyNote = executeOptions.readonly ? " [READ-ONLY MODE]" : "";
-  const maxRowsNote = executeOptions.maxRows ? ` (limited to ${executeOptions.maxRows} rows)` : "";
+  const maxRowsNote = executeOptions.maxRows ? ` (limited to ${executeOptions.maxRows} rows; capped results carry "truncated": true)` : "";
   const description = isSingleSource ? `${userDescPrefix}Execute SQL queries on the ${dbType} database${readonlyNote}${maxRowsNote}` : `${userDescPrefix}Execute SQL queries on the '${sourceId}' ${dbType} database${readonlyNote}${maxRowsNote}`;
   const isReadonly = isReadOnlyPolicy(policyFromReadonly(executeOptions.readonly));
   const annotations = {
@@ -1909,7 +1913,7 @@ See documentation for more details on configuring database connections.
     const sources = sourceConfigsData.sources;
     console.error(`Configuration source: ${sourceConfigsData.source}`);
     await connectorManager.connectWithSources(sources);
-    const { initializeToolRegistry: initializeToolRegistry2 } = await import("./registry-XMEJF7WW.js");
+    const { initializeToolRegistry: initializeToolRegistry2 } = await import("./registry-6ABK3M6V.js");
     initializeToolRegistry2({
       sources: sourceConfigsData.sources,
       tools: sourceConfigsData.tools
@@ -2064,11 +2068,11 @@ See documentation for more details on configuring database connections.
 
 // src/index.ts
 var connectorModules = [
-  { load: () => import("./postgres-6XY2GPQV.js"), name: "PostgreSQL", driver: "pg" },
-  { load: () => import("./sqlserver-IIGRXGYK.js"), name: "SQL Server", driver: "mssql" },
-  { load: () => import("./sqlite-CZE6Z36Y.js"), name: "SQLite", driver: "node:sqlite" },
-  { load: () => import("./mysql-RLDQI3SJ.js"), name: "MySQL", driver: "mysql2" },
-  { load: () => import("./mariadb-E33EXGJZ.js"), name: "MariaDB", driver: "mariadb" }
+  { load: () => import("./postgres-2FHS64EO.js"), name: "PostgreSQL", driver: "pg" },
+  { load: () => import("./sqlserver-WNVSBFJ3.js"), name: "SQL Server", driver: "mssql" },
+  { load: () => import("./sqlite-ASYMU5BI.js"), name: "SQLite", driver: "node:sqlite" },
+  { load: () => import("./mysql-GXDUNLJ6.js"), name: "MySQL", driver: "mysql2" },
+  { load: () => import("./mariadb-DQ6P57IX.js"), name: "MariaDB", driver: "mariadb" }
 ];
 loadConnectors(connectorModules).then(() => main()).catch((error) => {
   console.error("Fatal error:", error);

package/dist/{mariadb-E33EXGJZ.js → mariadb-DQ6P57IX.js}

@@ -5,7 +5,7 @@ import {
   parseQueryResultSets,
   requireDatabaseInDSN,
   withReadOnlyTransaction
-} from "./chunk-QEFMUQJ2.js";
+} from "./chunk-A4TSDCPY.js";
 import "./chunk-FU2ZJE4E.js";
 import {
   quoteIdentifier
@@ -13,13 +13,13 @@ import {
 import {
   SQLRowLimiter,
   closeQuietly
-} from "./chunk-RSB7DPO2.js";
+} from "./chunk-6QETXS44.js";
 import {
   ConnectorRegistry,
   SafeURL,
   obfuscateDSNPassword,
   splitSQLStatements
-} from "./chunk-WIQ4DWGY.js";
+} from "./chunk-MF6LSVWK.js";
 
 // src/connectors/mariadb/index.ts
 import * as mariadb from "mariadb";
@@ -506,11 +506,13 @@ var MariaDBConnector = class _MariaDBConnector {
         async () => {
           const statements = splitSQLStatements(sql, "mariadb");
           let processedSQL = sql;
+          let probes = [];
           if (options.maxRows) {
-            const processedStatements = statements.map(
-              (statement) => SQLRowLimiter.applyMaxRows(statement, options.maxRows)
+            const rewrites = statements.map(
+              (statement) => SQLRowLimiter.applyMaxRowsWithTruncationProbe(statement, options.maxRows)
             );
-            processedSQL = processedStatements.join("; ");
+            probes = rewrites.map((rewrite) => rewrite.probeApplied);
+            processedSQL = rewrites.map((rewrite) => rewrite.sql).join("; ");
             if (sql.trim().endsWith(";")) {
               processedSQL += ";";
             }
@@ -522,6 +524,11 @@ var MariaDBConnector = class _MariaDBConnector {
             results = await conn.query(processedSQL);
           }
           const resultSets = parseQueryResultSets(results, statements);
+          if (resultSets.length === probes.length) {
+            resultSets.forEach(
+              (set, index) => SQLRowLimiter.flagTruncation(set, options.maxRows, probes[index])
+            );
+          }
           return { resultSets };
         }
       );

package/dist/{mysql-RLDQI3SJ.js → mysql-GXDUNLJ6.js}

@@ -6,7 +6,7 @@ import {
   parseQueryResultSets,
   requireDatabaseInDSN,
   withReadOnlyTransaction
-} from "./chunk-QEFMUQJ2.js";
+} from "./chunk-A4TSDCPY.js";
 import "./chunk-FU2ZJE4E.js";
 import {
   quoteIdentifier
@@ -14,13 +14,13 @@ import {
 import {
   SQLRowLimiter,
   closeQuietly
-} from "./chunk-RSB7DPO2.js";
+} from "./chunk-6QETXS44.js";
 import {
   ConnectorRegistry,
   SafeURL,
   obfuscateDSNPassword,
   splitSQLStatements
-} from "./chunk-WIQ4DWGY.js";
+} from "./chunk-MF6LSVWK.js";
 
 // src/connectors/mysql/index.ts
 import mysql from "mysql2/promise";
@@ -517,11 +517,13 @@ var _MySQLConnector = class _MySQLConnector {
         async () => {
           const statements = splitSQLStatements(sql, "mysql");
           let processedSQL = sql;
+          let probes = [];
           if (options.maxRows) {
-            const processedStatements = statements.map(
-              (statement) => SQLRowLimiter.applyMaxRows(statement, options.maxRows)
+            const rewrites = statements.map(
+              (statement) => SQLRowLimiter.applyMaxRowsWithTruncationProbe(statement, options.maxRows)
             );
-            processedSQL = processedStatements.join("; ");
+            probes = rewrites.map((rewrite) => rewrite.probeApplied);
+            processedSQL = rewrites.map((rewrite) => rewrite.sql).join("; ");
             if (sql.trim().endsWith(";")) {
               processedSQL += ";";
             }
@@ -534,6 +536,11 @@ var _MySQLConnector = class _MySQLConnector {
           }
           const [firstResult] = results;
           const resultSets = parseQueryResultSets(firstResult, statements);
+          if (resultSets.length === probes.length) {
+            resultSets.forEach(
+              (set, index) => SQLRowLimiter.flagTruncation(set, options.maxRows, probes[index])
+            );
+          }
           return { resultSets };
         }
       );

package/dist/{postgres-6XY2GPQV.js → postgres-2FHS64EO.js}

@@ -7,13 +7,13 @@ import {
 import {
   SQLRowLimiter,
   closeQuietly
-} from "./chunk-RSB7DPO2.js";
+} from "./chunk-6QETXS44.js";
 import {
   ConnectorRegistry,
   SafeURL,
   obfuscateDSNPassword,
   splitSQLStatements
-} from "./chunk-WIQ4DWGY.js";
+} from "./chunk-MF6LSVWK.js";
 
 // src/connectors/postgres/index.ts
 import fs from "fs";
@@ -557,17 +557,22 @@ var PostgresConnector = class _PostgresConnector {
     try {
       const statements = splitSQLStatements(sql, "postgres");
       if (statements.length === 1) {
-        const processedStatement = SQLRowLimiter.applyMaxRows(statements[0], options.maxRows);
+        const { sql: processedStatement, probeApplied } = SQLRowLimiter.applyMaxRowsWithTruncationProbe(
+          statements[0],
+          options.maxRows
+        );
         if (options.readonly) {
           await client.query("BEGIN READ ONLY");
           try {
             const result2 = parameters && parameters.length > 0 ? await client.query(processedStatement, parameters) : await client.query(processedStatement);
             await client.query("COMMIT");
-            return {
-              resultSets: [
-                { sql: statements[0], rows: result2.rows, rowCount: result2.rowCount ?? result2.rows.length }
-              ]
+            const resultSet2 = {
+              sql: statements[0],
+              rows: result2.rows,
+              rowCount: result2.rowCount ?? result2.rows.length
             };
+            SQLRowLimiter.flagTruncation(resultSet2, options.maxRows, probeApplied);
+            return { resultSets: [resultSet2] };
           } catch (error) {
             try {
               await client.query("ROLLBACK");
@@ -582,11 +587,13 @@ var PostgresConnector = class _PostgresConnector {
         } else {
           result = await client.query(processedStatement);
         }
-        return {
-          resultSets: [
-            { sql: statements[0], rows: result.rows, rowCount: result.rowCount ?? result.rows.length }
-          ]
+        const resultSet = {
+          sql: statements[0],
+          rows: result.rows,
+          rowCount: result.rowCount ?? result.rows.length
         };
+        SQLRowLimiter.flagTruncation(resultSet, options.maxRows, probeApplied);
+        return { resultSets: [resultSet] };
       } else {
         if (parameters && parameters.length > 0) {
           throw new Error("Parameters are not supported for multi-statement queries in PostgreSQL");
@@ -595,13 +602,18 @@ var PostgresConnector = class _PostgresConnector {
         await client.query(options.readonly ? "BEGIN READ ONLY" : "BEGIN");
         try {
           for (let statement of statements) {
-            const processedStatement = SQLRowLimiter.applyMaxRows(statement, options.maxRows);
+            const { sql: processedStatement, probeApplied } = SQLRowLimiter.applyMaxRowsWithTruncationProbe(
+              statement,
+              options.maxRows
+            );
             const result = await client.query(processedStatement);
-            resultSets.push({
+            const resultSet = {
               sql: statement,
               rows: result.rows ?? [],
               rowCount: result.rowCount ?? result.rows?.length ?? 0
-            });
+            };
+            SQLRowLimiter.flagTruncation(resultSet, options.maxRows, probeApplied);
+            resultSets.push(resultSet);
           }
           await client.query("COMMIT");
         } catch (error) {