@bytebase/dbhub 0.23.0 → 1.0.0

package/README.md

@@ -84,6 +84,10 @@ npx @bytebase/dbhub@latest --transport http --port 8080 --dsn "postgres://user:p
 
 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.
 
+**Claude Code Plugin:**
+
+For Claude Code, the [DBHub plugin](https://dbhub.ai/claude-code-plugin) registers the MCP server with one install command — Claude Code prompts for your connection string and stores it in secure storage — and adds `/dbhub:setup` and `/dbhub:explore` skills. Read-only by design, like the MCP Bundle.
+
 **Demo Mode:**
 
 ```bash
@@ -99,6 +103,8 @@ 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`.
+>
+> DBHub serves both MCP protocol eras on the same `/mcp` endpoint: the stateless **2026-07-28** revision (cacheable `tools/list`, no session state — safe behind round-robin load balancers) and the 2025-era Streamable HTTP protocol for older clients. 2026-era clients send the standard `Mcp-Method` / `Mcp-Name` headers on every request, so a fronting gateway or WAF can route and rate-limit `execute_sql` separately from `search_objects` without parsing JSON bodies.
 
 See [Command-Line Options](https://dbhub.ai/config/command-line) for all available parameters.
 

package/dist/{chunk-RTB262PR.js → chunk-DUCNPMNW.js}

@@ -1,3 +1,26 @@
+import {
+  obfuscateDSNPassword
+} from "./chunk-JEZZN2YZ.js";
+
+// 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)) {
@@ -54,7 +77,37 @@ function parseQueryResults(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 {
+  MissingDatabaseError,
+  requireDatabaseInDSN,
   extractAffectedRows,
-  parseQueryResults
+  parseQueryResults,
+  withReadOnlyTransaction,
+  isTiDBVersion
 };

package/dist/chunk-JO7YQPBQ.js

@@ -0,0 +1,130 @@
+import {
+  stripCommentsAndStrings
+} from "./chunk-JEZZN2YZ.js";
+
+// src/utils/allowed-keywords.ts
+var allowedKeywords = {
+  postgres: ["select", "with", "explain", "show"],
+  mysql: ["select", "with", "explain", "show", "describe", "desc"],
+  mariadb: ["select", "with", "explain", "show", "describe", "desc"],
+  sqlite: ["select", "with", "explain", "pragma"],
+  // SQL Server has no native EXPLAIN statement; the connector translates a
+  // leading `EXPLAIN` into a SET SHOWPLAN_XML request (see SQLServerConnector).
+  sqlserver: ["select", "with", "explain"]
+};
+var mutatingKeywords = [
+  "insert",
+  "update",
+  "delete",
+  "drop",
+  "alter",
+  "create",
+  "truncate",
+  "merge",
+  "grant",
+  "revoke",
+  "rename"
+];
+var mutatingPattern = new RegExp(
+  `\\b(?:${mutatingKeywords.join("|")})\\b`,
+  "i"
+);
+var mutatingPatternWithReplace = new RegExp(
+  `\\b(?:${mutatingKeywords.join("|")}|replace\\s+(?:(?:low_priority|delayed)\\s+)?into)\\b`,
+  "i"
+);
+var sqlServerDynamicSqlKeywords = [
+  "execute",
+  "exec",
+  "sp_executesql",
+  "xp_cmdshell"
+];
+var sqlServerDynamicSqlPattern = new RegExp(
+  `\\b(?:${sqlServerDynamicSqlKeywords.join("|")})\\b`,
+  "i"
+);
+var sqlServerPassThroughKeywords = [
+  "openquery",
+  "openrowset",
+  "opendatasource"
+];
+var sqlServerPassThroughPattern = new RegExp(
+  `\\b(?:${sqlServerPassThroughKeywords.join("|")})\\s*\\(`,
+  "i"
+);
+var mutatingPatternSqlServer = new RegExp(
+  `\\b(?:${[...mutatingKeywords, ...sqlServerDynamicSqlKeywords].join("|")})\\b`,
+  "i"
+);
+var mutatingPatterns = {
+  postgres: mutatingPattern,
+  mysql: mutatingPatternWithReplace,
+  mariadb: mutatingPatternWithReplace,
+  sqlite: mutatingPatternWithReplace,
+  sqlserver: mutatingPatternSqlServer
+};
+var selectIntoPattern = /\bselect\b[\s\S]+\binto\b/i;
+var sqliteReadOnlyArgPragmas = /* @__PURE__ */ new Set([
+  "table_info",
+  "index_info",
+  "index_list",
+  "foreign_key_list"
+]);
+var sqlitePragmaParenPattern = /^pragma\s+(?:[a-z0-9_]+\.)?([a-z0-9_]+)\s*\(/;
+var explainAnalyzePattern = /^explain\s+(?:\([^)]*\banalyze\b(?!\s*(?:=\s*)?(?:false|off|0)\b)[^)]*\)|\banalyze\b(?!\s*(?:=\s*)?(?:false|off|0)\b)(?:\s+verbose\b)?)/i;
+function isReadOnlySQL(sql, connectorType) {
+  return checkReadOnly(
+    stripCommentsAndStrings(sql, connectorType).trim().toLowerCase(),
+    connectorType
+  );
+}
+function checkReadOnly(cleanedSQL, connectorType) {
+  if (!cleanedSQL) {
+    return false;
+  }
+  const firstWord = cleanedSQL.match(/\S+/)?.[0] ?? "";
+  const keywordList = allowedKeywords[connectorType] || [];
+  if (!keywordList.includes(firstWord)) {
+    return false;
+  }
+  if (connectorType === "sqlserver" && sqlServerPassThroughPattern.test(cleanedSQL)) {
+    return false;
+  }
+  if (firstWord === "with") {
+    const pattern = mutatingPatterns[connectorType] ?? mutatingPattern;
+    if (pattern.test(cleanedSQL)) {
+      return false;
+    }
+  }
+  if (firstWord === "pragma" && connectorType === "sqlite") {
+    if (cleanedSQL.includes("=")) {
+      return false;
+    }
+    const parenMatch = cleanedSQL.match(sqlitePragmaParenPattern);
+    if (parenMatch && !sqliteReadOnlyArgPragmas.has(parenMatch[1])) {
+      return false;
+    }
+  }
+  if ((firstWord === "select" || firstWord === "with") && selectIntoPattern.test(cleanedSQL)) {
+    return false;
+  }
+  if (firstWord === "explain") {
+    const m = explainAnalyzePattern.exec(cleanedSQL);
+    if (m) {
+      const afterExplain = cleanedSQL.slice(m[0].length).trim();
+      if (afterExplain && !checkReadOnly(afterExplain, connectorType)) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
+export {
+  allowedKeywords,
+  sqlServerDynamicSqlKeywords,
+  sqlServerDynamicSqlPattern,
+  sqlServerPassThroughKeywords,
+  sqlServerPassThroughPattern,
+  isReadOnlySQL
+};

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

@@ -580,55 +580,59 @@ function parseCommandLineArgs() {
   }
   return parsedManually;
 }
-function loadEnvFiles() {
+function findEnvFile() {
   const isDevelopment = process.env.NODE_ENV === "development" || process.argv[1]?.includes("tsx");
   const envFileNames = isDevelopment ? [".env.local", ".env"] : [".env"];
   const envPaths = [];
   for (const fileName of envFileNames) {
     envPaths.push(
-      fileName,
+      path.join(process.cwd(), fileName),
       // Current working directory
-      path.join(__dirname, "..", "..", fileName),
+      path.join(__dirname, "..", "..", fileName)
       // Two levels up (src/config -> src -> root)
-      path.join(process.cwd(), fileName)
-      // Explicit current working directory
     );
   }
   for (const envPath of envPaths) {
-    console.error(`Checking for env file: ${envPath}`);
     if (fs.existsSync(envPath)) {
-      dotenv.config({ path: envPath });
-      if (process.env.READONLY !== void 0) {
-        console.error("\nERROR: READONLY environment variable is no longer supported.");
-        console.error("Use dbhub.toml with [[tools]] configuration instead:\n");
-        console.error("  [[sources]]");
-        console.error('  id = "default"');
-        console.error('  dsn = "..."\n');
-        console.error("  [[tools]]");
-        console.error('  name = "execute_sql"');
-        console.error('  source = "default"');
-        console.error("  readonly = true\n");
-        console.error("See https://dbhub.ai/tools/execute-sql#read-only-mode for details.\n");
-        process.exit(1);
-      }
-      if (process.env.MAX_ROWS !== void 0) {
-        console.error("\nERROR: MAX_ROWS environment variable is no longer supported.");
-        console.error("Use dbhub.toml with [[tools]] configuration instead:\n");
-        console.error("  [[sources]]");
-        console.error('  id = "default"');
-        console.error('  dsn = "..."\n');
-        console.error("  [[tools]]");
-        console.error('  name = "execute_sql"');
-        console.error('  source = "default"');
-        console.error("  max_rows = 1000\n");
-        console.error("See https://dbhub.ai/tools/execute-sql#row-limiting for details.\n");
-        process.exit(1);
-      }
-      return path.basename(envPath);
+      return envPath;
     }
   }
   return null;
 }
+function loadEnvFiles() {
+  const envPath = findEnvFile();
+  if (envPath) {
+    dotenv.config({ path: envPath });
+    if (process.env.READONLY !== void 0) {
+      console.error("\nERROR: READONLY environment variable is no longer supported.");
+      console.error("Use dbhub.toml with [[tools]] configuration instead:\n");
+      console.error("  [[sources]]");
+      console.error('  id = "default"');
+      console.error('  dsn = "..."\n');
+      console.error("  [[tools]]");
+      console.error('  name = "execute_sql"');
+      console.error('  source = "default"');
+      console.error("  readonly = true\n");
+      console.error("See https://dbhub.ai/tools/execute-sql#read-only-mode for details.\n");
+      process.exit(1);
+    }
+    if (process.env.MAX_ROWS !== void 0) {
+      console.error("\nERROR: MAX_ROWS environment variable is no longer supported.");
+      console.error("Use dbhub.toml with [[tools]] configuration instead:\n");
+      console.error("  [[sources]]");
+      console.error('  id = "default"');
+      console.error('  dsn = "..."\n');
+      console.error("  [[tools]]");
+      console.error('  name = "execute_sql"');
+      console.error('  source = "default"');
+      console.error("  max_rows = 1000\n");
+      console.error("See https://dbhub.ai/tools/execute-sql#row-limiting for details.\n");
+      process.exit(1);
+    }
+    return path.basename(envPath);
+  }
+  return null;
+}
 function isDemoMode() {
   const args = parseCommandLineArgs();
   return args.demo === "true";
@@ -923,6 +927,9 @@ function resolveSSHConfig() {
   };
 }
 async function resolveSourceConfigs() {
+  if (parseCommandLineArgs().config) {
+    loadEnvFiles();
+  }
   if (!isDemoMode()) {
     const tomlConfig = loadTomlConfig();
     if (tomlConfig) {
@@ -932,6 +939,11 @@ async function resolveSourceConfigs() {
           "The --id flag cannot be used with TOML configuration. TOML config defines source IDs directly. Either remove the --id flag or use command-line DSN configuration instead."
         );
       }
+      if (parseCommandLineArgs().dsn) {
+        throw new Error(
+          `The --dsn flag cannot be used with TOML configuration (${tomlConfig.source}). TOML config defines database sources directly and supports multiple databases, while a DSN configures a single database. Either remove the --dsn flag or drop the --config flag.`
+        );
+      }
       return tomlConfig;
     }
   }
@@ -1039,8 +1051,9 @@ function loadTomlConfig() {
 }
 function resolveTomlConfigPath() {
   const args = parseCommandLineArgs();
-  if (args.config) {
-    const configPath = expandHomeDir(args.config);
+  const configValue = requireFlagValue("config", args, "./dbhub.toml");
+  if (configValue) {
+    const configPath = expandHomeDir(configValue);
     if (!fs2.existsSync(configPath)) {
       throw new Error(
         `Configuration file specified by --config flag not found: ${configPath}`
@@ -1048,10 +1061,6 @@ function resolveTomlConfigPath() {
     }
     return configPath;
   }
-  const defaultConfigPath = path2.join(process.cwd(), "dbhub.toml");
-  if (fs2.existsSync(defaultConfigPath)) {
-    return defaultConfigPath;
-  }
   return null;
 }
 function validateTomlConfig(config, configPath) {
@@ -1206,6 +1215,11 @@ function validateDSNFieldConflicts(source, configPath) {
     if (source.database && info.database && source.database !== info.database) {
       conflict("database", source.database, info.database);
     }
+    if (source.database && !info.database) {
+      throw new Error(
+        `Configuration file ${configPath}: source '${source.id}' has a 'database' field but the DSN names no database. The field is ignored at connection time \u2014 add the database to the DSN, or use individual connection parameters instead of a DSN.`
+      );
+    }
     if (source.user && info.user && source.user !== info.user) {
       conflict("user", source.user, info.user);
     }

package/dist/{chunk-BXXHWEQS.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);
   }
@@ -122,6 +124,15 @@ var SQLRowLimiter = class {
   }
 };
 
+// src/utils/resource-cleanup.ts
+async function closeQuietly(close) {
+  try {
+    await close();
+  } catch {
+  }
+}
+
 export {
-  SQLRowLimiter
+  SQLRowLimiter,
+  closeQuietly
 };