@bytebase/dbhub 0.22.2 → 0.22.4

package/dist/{chunk-MEBWJMLY.js → chunk-DN45LGY4.js}

@@ -1094,6 +1094,92 @@ function validateToolsConfig(tools, sources, configPath) {
     }
   }
 }
+function getRawDSNQueryParam(dsn, key) {
+  const queryStart = dsn.indexOf("?");
+  if (queryStart === -1) {
+    return null;
+  }
+  for (const pair of dsn.substring(queryStart + 1).split("&")) {
+    if (pair === "") {
+      continue;
+    }
+    const eq = pair.indexOf("=");
+    const rawKey = eq === -1 ? pair : pair.substring(0, eq);
+    if (rawKey === key) {
+      const rawValue = eq === -1 ? "" : pair.substring(eq + 1);
+      try {
+        return decodeURIComponent(rawValue);
+      } catch {
+        return rawValue;
+      }
+    }
+  }
+  return null;
+}
+function validateDSNFieldConflicts(source, configPath) {
+  const conflict = (field, fieldValue, dsnValue) => {
+    throw new Error(
+      `Configuration file ${configPath}: source '${source.id}' has conflicting ${field}: the DSN specifies '${dsnValue}' but the ${field} field is '${fieldValue}'. Set ${field} in only one place, or make the two values match.`
+    );
+  };
+  const info = parseConnectionInfoFromDSN(source.dsn);
+  if (source.type && info?.type && source.type !== info.type) {
+    conflict("type", source.type, info.type);
+  }
+  if (info?.type === "sqlite") {
+    return;
+  }
+  let url;
+  try {
+    url = new SafeURL(source.dsn);
+  } catch {
+    return;
+  }
+  if (info) {
+    if (source.host && info.host && source.host.toLowerCase() !== info.host.toLowerCase()) {
+      conflict("host", source.host, info.host);
+    }
+    if (source.port !== void 0 && info.port !== void 0 && source.port !== info.port) {
+      conflict("port", String(source.port), String(info.port));
+    }
+    if (source.database && info.database && source.database !== info.database) {
+      conflict("database", source.database, info.database);
+    }
+    if (source.user && info.user && source.user !== info.user) {
+      conflict("user", source.user, info.user);
+    }
+  }
+  if (source.password && source.password !== url.password) {
+    if (!url.password) {
+      throw new Error(
+        `Configuration file ${configPath}: source '${source.id}' has a 'password' field but the DSN has no password. The field is ignored at connection time \u2014 add the password to the DSN, or use individual connection parameters instead of a DSN.`
+      );
+    }
+    throw new Error(
+      `Configuration file ${configPath}: source '${source.id}' has a 'password' field that conflicts with the password in the DSN. Set the password in only one place.`
+    );
+  }
+  const dsnSslmode = getRawDSNQueryParam(source.dsn, "sslmode");
+  if (source.sslmode && dsnSslmode !== null && dsnSslmode !== source.sslmode) {
+    conflict("sslmode", source.sslmode, dsnSslmode);
+  }
+  const dsnSslrootcert = getRawDSNQueryParam(source.dsn, "sslrootcert");
+  if (source.sslrootcert && dsnSslrootcert !== null && expandHomeDir(source.sslrootcert) !== expandHomeDir(dsnSslrootcert)) {
+    conflict("sslrootcert", expandHomeDir(source.sslrootcert), expandHomeDir(dsnSslrootcert));
+  }
+  const dsnInstanceName = getRawDSNQueryParam(source.dsn, "instanceName");
+  if (source.instanceName && dsnInstanceName !== null && dsnInstanceName !== source.instanceName) {
+    conflict("instanceName", source.instanceName, dsnInstanceName);
+  }
+  const dsnAuthentication = getRawDSNQueryParam(source.dsn, "authentication");
+  if (source.authentication && dsnAuthentication !== null && dsnAuthentication !== source.authentication) {
+    conflict("authentication", source.authentication, dsnAuthentication);
+  }
+  const dsnDomain = getRawDSNQueryParam(source.dsn, "domain");
+  if (source.domain && dsnDomain !== null && dsnDomain !== source.domain) {
+    conflict("domain", source.domain, dsnDomain);
+  }
+}
 function validateSourceConfig(source, configPath) {
   const hasConnectionParams = source.type && (source.type === "sqlite" ? source.database : source.host);
   if (!source.dsn && !hasConnectionParams) {
@@ -1176,6 +1262,9 @@ function validateSourceConfig(source, configPath) {
       );
     }
   }
+  if (source.dsn) {
+    validateDSNFieldConflicts(source, configPath);
+  }
   if (source.sslrootcert !== void 0) {
     if (source.sslmode !== "verify-ca" && source.sslmode !== "verify-full") {
       throw new Error(
@@ -1350,9 +1439,51 @@ function expandHomeDir(filePath) {
   }
   return filePath;
 }
+function mergeSourceFieldsIntoDSN(dsn, source) {
+  if (source.type === "sqlite") {
+    return dsn;
+  }
+  try {
+    new SafeURL(dsn);
+  } catch {
+    return dsn;
+  }
+  const hasParam = (key) => getRawDSNQueryParam(dsn, key) !== null;
+  const additions = [];
+  if (source.type === "sqlserver") {
+    if (source.instanceName && !hasParam("instanceName")) {
+      additions.push(`instanceName=${encodeURIComponent(source.instanceName)}`);
+    }
+    if (source.authentication && !hasParam("authentication")) {
+      additions.push(`authentication=${encodeURIComponent(source.authentication)}`);
+    }
+    if (source.domain && !hasParam("domain")) {
+      additions.push(`domain=${encodeURIComponent(source.domain)}`);
+    }
+  }
+  if (source.sslmode && !hasParam("sslmode")) {
+    additions.push(`sslmode=${source.sslmode}`);
+  }
+  if (source.sslrootcert && source.type === "postgres" && (source.sslmode === "verify-ca" || source.sslmode === "verify-full") && !hasParam("sslrootcert")) {
+    const expandedCertPath = expandHomeDir(source.sslrootcert);
+    additions.push(`sslrootcert=${encodeURIComponent(expandedCertPath)}`);
+  }
+  if (additions.length === 0) {
+    return dsn;
+  }
+  let separator;
+  if (!dsn.includes("?")) {
+    separator = "?";
+  } else if (dsn.endsWith("?") || dsn.endsWith("&")) {
+    separator = "";
+  } else {
+    separator = "&";
+  }
+  return `${dsn}${separator}${additions.join("&")}`;
+}
 function buildDSNFromSource(source) {
   if (source.dsn) {
-    return source.dsn;
+    return mergeSourceFieldsIntoDSN(source.dsn, source);
   }
   if (!source.type) {
     throw new Error(
@@ -1434,6 +1565,53 @@ async function generateRdsAuthToken(params) {
   return signer.getAuthToken();
 }
 
+// src/utils/error-classifier.ts
+var TUNNEL_ERROR_MARKER = "__dbhubSSHTunnelError";
+var NETWORK_CODES = /* @__PURE__ */ new Set([
+  "ECONNREFUSED",
+  "ETIMEDOUT",
+  "ENOTFOUND",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ECONNRESET"
+]);
+var AUTH_CODES = {
+  postgres: ["28P01", "28000"],
+  mysql: ["ER_ACCESS_DENIED_ERROR", 1045, 1698],
+  mariadb: ["ER_ACCESS_DENIED_ERROR", 1045, 1698],
+  sqlserver: ["ELOGIN"],
+  sqlite: []
+  // no network/auth layer
+};
+function unreachableMessage(sourceId) {
+  return `Source '${sourceId}' is unreachable. Verify the database is running and reachable (host, port, network), then retry.`;
+}
+function authMessage(sourceId) {
+  return `Authentication failed for source '${sourceId}'. Verify the credentials/access for this source are valid, then retry.`;
+}
+function tunnelMessage(sourceId) {
+  return `SSH tunnel for source '${sourceId}' failed to establish. Verify SSH host/credentials and bastion reachability, then retry.`;
+}
+function classifyConnectionError(error, connectorType, sourceId) {
+  if (!error || typeof error !== "object") {
+    return null;
+  }
+  const err = error;
+  if (err[TUNNEL_ERROR_MARKER] === true) {
+    return { code: "TUNNEL_FAILED", message: tunnelMessage(sourceId) };
+  }
+  const code = err.code;
+  if (typeof code === "string" && NETWORK_CODES.has(code)) {
+    return { code: "SOURCE_UNREACHABLE", message: unreachableMessage(sourceId) };
+  }
+  const authCodes = AUTH_CODES[connectorType];
+  const errno = err.errno;
+  if (typeof code === "string" && authCodes.includes(code) || typeof errno === "number" && authCodes.includes(errno)) {
+    return { code: "AUTH_FAILED", message: authMessage(sourceId) };
+  }
+  return null;
+}
+
 // src/connectors/manager.ts
 var managerInstance = null;
 var AWS_IAM_TOKEN_REFRESH_MS = 14 * 60 * 1e3;
@@ -1574,10 +1752,18 @@ var ConnectorManager = class {
       const targetHost = url.hostname;
       const targetPort = parseInt(url.port) || this.getDefaultPort(dsn);
       const tunnel = new SSHTunnel();
-      const tunnelInfo = await tunnel.establish(sshConfig, {
-        targetHost,
-        targetPort
-      });
+      let tunnelInfo;
+      try {
+        tunnelInfo = await tunnel.establish(sshConfig, {
+          targetHost,
+          targetPort
+        });
+      } catch (error) {
+        if (error && typeof error === "object") {
+          error[TUNNEL_ERROR_MARKER] = true;
+        }
+        throw error;
+      }
       url.hostname = "127.0.0.1";
       url.port = tunnelInfo.localPort.toString();
       actualDSN = url.toString();
@@ -2190,6 +2376,7 @@ export {
   BUILTIN_TOOL_SEARCH_OBJECTS,
   loadTomlConfig,
   resolveTomlConfigPath,
+  classifyConnectionError,
   ConnectorManager,
   mapArgumentsToArray,
   ToolRegistry,

package/dist/index.js

@@ -3,6 +3,7 @@ import {
   BUILTIN_TOOL_EXECUTE_SQL,
   BUILTIN_TOOL_SEARCH_OBJECTS,
   ConnectorManager,
+  classifyConnectionError,
   getToolRegistry,
   initializeToolRegistry,
   isDemoMode,
@@ -13,7 +14,7 @@ import {
   resolveSourceConfigs,
   resolveTomlConfigPath,
   resolveTransport
-} from "./chunk-MEBWJMLY.js";
+} from "./chunk-DN45LGY4.js";
 import {
   loadConnectors
 } from "./chunk-WVVMH6FJ.js";
@@ -99,7 +100,9 @@ var allowedKeywords = {
   mysql: ["select", "with", "explain", "show", "describe", "desc"],
   mariadb: ["select", "with", "explain", "show", "describe", "desc"],
   sqlite: ["select", "with", "explain", "pragma"],
-  sqlserver: ["select", "with", "explain", "showplan"]
+  // 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",
@@ -246,6 +249,20 @@ function trackToolRequest(metadata, startTime, extra, success, error) {
     error
   });
 }
+function tryClassifyConnectionError(error, rawSourceId, displaySourceId) {
+  let connectorType;
+  try {
+    connectorType = ConnectorManager.getSourceConfig(rawSourceId)?.type;
+  } catch {
+    return null;
+  }
+  if (!connectorType) return null;
+  const classified = classifyConnectionError(error, connectorType, displaySourceId);
+  if (!classified) return null;
+  return createToolErrorResponse(classified.message, classified.code, {
+    source_id: displaySourceId
+  });
+}
 
 // src/tools/execute-sql.ts
 var executeSqlSchema = {
@@ -290,6 +307,8 @@ function createExecuteSqlToolHandler(sourceId) {
     } catch (error) {
       success = false;
       errorMessage = error.message;
+      const classified = tryClassifyConnectionError(error, sourceId, effectiveSourceId);
+      if (classified) return classified;
       return createToolErrorResponse(errorMessage, "EXECUTION_ERROR");
     } finally {
       trackToolRequest(
@@ -311,16 +330,25 @@ function createExecuteSqlToolHandler(sourceId) {
 import { z as z2 } from "zod";
 var searchDatabaseObjectsSchema = {
   object_type: z2.enum(["schema", "table", "view", "column", "procedure", "function", "index"]).describe("Object type to search"),
-  pattern: z2.string().optional().default("%").describe("LIKE pattern (% = any chars, _ = one char). Default: %"),
+  pattern: z2.string().optional().default("%").describe("LIKE pattern (% = any chars, _ = one char)"),
   schema: z2.string().optional().describe("Filter to schema"),
   table: z2.string().optional().describe("Filter to table (requires schema; column/index only)"),
   detail_level: z2.enum(["names", "summary", "full"]).default("names").describe("Detail: names (minimal), summary (metadata), full (all)"),
-  limit: z2.number().int().positive().max(1e3).default(100).describe("Max results (default: 100, max: 1000)")
+  limit: z2.number().int().positive().max(1e3).default(100).describe("Max results")
 };
 function likePatternToRegex(pattern) {
   const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/%/g, ".*").replace(/_/g, ".");
   return new RegExp(`^${escaped}$`, "i");
 }
+async function resolveDefaultSchemas(connector) {
+  if (connector.getDefaultSchema) {
+    const defaultSchema = await connector.getDefaultSchema();
+    if (defaultSchema) {
+      return [defaultSchema];
+    }
+  }
+  return connector.getSchemas();
+}
 async function getTableRowCount(connector, tableName, schemaName) {
   try {
     if (connector.getTableRowCount) {
@@ -348,7 +376,7 @@ async function getTableComment(connector, tableName, schemaName) {
   }
 }
 async function searchSchemas(connector, pattern, detailLevel, limit) {
-  const schemas = await connector.getSchemas();
+  const schemas = await resolveDefaultSchemas(connector);
   const regex = likePatternToRegex(pattern);
   const matched = schemas.filter((schema) => regex.test(schema)).slice(0, limit);
   if (detailLevel === "names") {
@@ -379,7 +407,7 @@ async function searchTables(connector, pattern, schemaFilter, detailLevel, limit
   if (schemaFilter) {
     schemasToSearch = [schemaFilter];
   } else {
-    schemasToSearch = await connector.getSchemas();
+    schemasToSearch = await resolveDefaultSchemas(connector);
   }
   for (const schemaName of schemasToSearch) {
     if (results.length >= limit) break;
@@ -532,7 +560,7 @@ async function searchColumns(connector, pattern, schemaFilter, tableFilter, deta
   if (schemaFilter) {
     schemasToSearch = [schemaFilter];
   } else {
-    schemasToSearch = await connector.getSchemas();
+    schemasToSearch = await resolveDefaultSchemas(connector);
   }
   for (const schemaName of schemasToSearch) {
     if (results.length >= limit) break;
@@ -589,7 +617,7 @@ async function searchProcedures(connector, pattern, schemaFilter, detailLevel, l
   if (schemaFilter) {
     schemasToSearch = [schemaFilter];
   } else {
-    schemasToSearch = await connector.getSchemas();
+    schemasToSearch = await resolveDefaultSchemas(connector);
   }
   for (const schemaName of schemasToSearch) {
     if (results.length >= limit) break;
@@ -637,7 +665,7 @@ async function searchIndexes(connector, pattern, schemaFilter, tableFilter, deta
   if (schemaFilter) {
     schemasToSearch = [schemaFilter];
   } else {
-    schemasToSearch = await connector.getSchemas();
+    schemasToSearch = await resolveDefaultSchemas(connector);
   }
   for (const schemaName of schemasToSearch) {
     if (results.length >= limit) break;
@@ -760,6 +788,8 @@ function createSearchDatabaseObjectsToolHandler(sourceId) {
     } catch (error) {
       success = false;
       errorMessage = error.message;
+      const classified = tryClassifyConnectionError(error, sourceId, effectiveSourceId);
+      if (classified) return classified;
       return createToolErrorResponse(
         `Error searching database objects: ${errorMessage}`,
         "SEARCH_ERROR"
@@ -864,7 +894,7 @@ function getSearchObjectsMetadata(sourceId) {
   const toolName = isSingleSource ? "search_objects" : `search_objects_${normalizeSourceId(sourceId)}`;
   const title = isSingleSource ? `Search Database Objects (${dbType})` : `Search Database Objects on ${sourceId} (${dbType})`;
   const userDescPrefix = buildSourceDescriptionPrefix(sourceConfig.description);
-  const description = isSingleSource ? `${userDescPrefix}Search and list database objects (schemas, tables, columns, procedures, functions, indexes) on the ${dbType} database` : `${userDescPrefix}Search and list database objects (schemas, tables, columns, procedures, functions, indexes) on the '${sourceId}' ${dbType} database`;
+  const description = isSingleSource ? `${userDescPrefix}Search and list database objects on the ${dbType} database` : `${userDescPrefix}Search and list database objects on the '${sourceId}' ${dbType} database`;
   return {
     name: toolName,
     description,
@@ -905,7 +935,7 @@ function buildSearchObjectsTool(sourceId) {
         name: "object_type",
         type: "string",
         required: true,
-        description: "Object type to search"
+        description: "Object type to search: schema, table, view, column, procedure, function, index"
       },
       {
         name: "pattern",
@@ -1053,6 +1083,8 @@ function createCustomToolHandler(toolConfig) {
     } catch (error) {
       success = false;
       errorMessage = error.message;
+      const classified = tryClassifyConnectionError(error, toolConfig.source, toolConfig.source);
+      if (classified) return classified;
       if (error instanceof z4.ZodError) {
         const issues = error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
         errorMessage = `Parameter validation failed: ${issues}`;
@@ -1546,7 +1578,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-FZPB5LRL.js");
+    const { initializeToolRegistry: initializeToolRegistry2 } = await import("./registry-OF5GPCBK.js");
     initializeToolRegistry2({
       sources: sourceConfigsData.sources,
       tools: sourceConfigsData.tools
@@ -1695,10 +1727,10 @@ See documentation for more details on configuring database connections.
 // src/index.ts
 var connectorModules = [
   { load: () => import("./postgres-EKVOBAH6.js"), name: "PostgreSQL", driver: "pg" },
-  { load: () => import("./sqlserver-5E7DSDVX.js"), name: "SQL Server", driver: "mssql" },
+  { load: () => import("./sqlserver-5TFVBCMA.js"), name: "SQL Server", driver: "mssql" },
   { load: () => import("./sqlite-2GBIF3MQ.js"), name: "SQLite", driver: "node:sqlite" },
-  { load: () => import("./mysql-NCKXNVZJ.js"), name: "MySQL", driver: "mysql2" },
-  { load: () => import("./mariadb-DVQM4MMM.js"), name: "MariaDB", driver: "mariadb" }
+  { load: () => import("./mysql-WG6UFALX.js"), name: "MySQL", driver: "mysql2" },
+  { load: () => import("./mariadb-ERB4D3RP.js"), name: "MariaDB", driver: "mariadb" }
 ];
 loadConnectors(connectorModules).then(() => main()).catch((error) => {
   console.error("Fatal error:", error);

package/dist/{mariadb-DVQM4MMM.js → mariadb-ERB4D3RP.js}

@@ -123,8 +123,9 @@ var MariaDBConnector = class _MariaDBConnector {
     }
     try {
       const rows = await this.pool.query(`
-        SELECT SCHEMA_NAME 
+        SELECT SCHEMA_NAME
         FROM INFORMATION_SCHEMA.SCHEMATA
+        WHERE SCHEMA_NAME NOT IN ('information_schema', 'performance_schema', 'mysql', 'sys')
         ORDER BY SCHEMA_NAME
       `);
       return rows.map((row) => row.SCHEMA_NAME);
@@ -447,6 +448,18 @@ var MariaDBConnector = class _MariaDBConnector {
     const rows = await this.pool.query("SELECT DATABASE() AS DB");
     return rows[0].DB;
   }
+  /**
+   * Default search scope = the database named in the DSN. DATABASE() returns
+   * null when the connection was opened without a database, in which case
+   * callers fall back to the full server-wide schema list.
+   */
+  async getDefaultSchema() {
+    if (!this.pool) {
+      throw new Error("Not connected to database");
+    }
+    const rows = await this.pool.query("SELECT DATABASE() AS DB");
+    return rows[0]?.DB ?? null;
+  }
   async executeSQL(sql, options, parameters) {
     if (!this.pool) {
       throw new Error("Not connected to database");

package/dist/{mysql-NCKXNVZJ.js → mysql-WG6UFALX.js}

@@ -129,8 +129,9 @@ var MySQLConnector = class _MySQLConnector {
     }
     try {
       const [rows] = await this.pool.query(`
-        SELECT SCHEMA_NAME 
+        SELECT SCHEMA_NAME
         FROM INFORMATION_SCHEMA.SCHEMATA
+        WHERE SCHEMA_NAME NOT IN ('information_schema', 'performance_schema', 'mysql', 'sys')
         ORDER BY SCHEMA_NAME
       `);
       return rows.map((row) => row.SCHEMA_NAME);
@@ -453,6 +454,18 @@ var MySQLConnector = class _MySQLConnector {
     const [rows] = await this.pool.query("SELECT DATABASE() AS DB");
     return rows[0].DB;
   }
+  /**
+   * Default search scope = the database named in the DSN. DATABASE() returns
+   * null when the connection was opened without a database, in which case
+   * callers fall back to the full server-wide schema list.
+   */
+  async getDefaultSchema() {
+    if (!this.pool) {
+      throw new Error("Not connected to database");
+    }
+    const [rows] = await this.pool.query("SELECT DATABASE() AS DB");
+    return rows[0]?.DB ?? null;
+  }
   async executeSQL(sql, options, parameters) {
     if (!this.pool) {
       throw new Error("Not connected to database");

package/dist/{registry-FZPB5LRL.js → registry-OF5GPCBK.js}

@@ -2,7 +2,7 @@ import {
   ToolRegistry,
   getToolRegistry,
   initializeToolRegistry
-} from "./chunk-MEBWJMLY.js";
+} from "./chunk-DN45LGY4.js";
 import "./chunk-WVVMH6FJ.js";
 import "./chunk-C7WEAPX4.js";
 export {

package/dist/{sqlserver-5E7DSDVX.js → sqlserver-5TFVBCMA.js}

@@ -7,7 +7,8 @@ import {
 import {
   ConnectorRegistry,
   SafeURL,
-  obfuscateDSNPassword
+  obfuscateDSNPassword,
+  stripCommentsAndStrings
 } from "./chunk-C7WEAPX4.js";
 
 // src/connectors/sqlserver/index.ts
@@ -135,7 +136,7 @@ Expected: ${expectedFormat}`
     }
   }
 };
-var SQLServerConnector = class _SQLServerConnector {
+var _SQLServerConnector = class _SQLServerConnector {
   constructor() {
     this.id = "sqlserver";
     this.name = "SQL Server";
@@ -457,6 +458,12 @@ var SQLServerConnector = class _SQLServerConnector {
     if (!this.connection) {
       throw new Error("Not connected to SQL Server database");
     }
+    const afterNoise = sqlQuery.slice(
+      sqlQuery.match(_SQLServerConnector.LEADING_NOISE)[0].length
+    );
+    if (/^explain\b/i.test(afterNoise)) {
+      return this.explainQuery(afterNoise.slice("explain".length).trim());
+    }
     try {
       let processedSQL = sqlQuery;
       if (options.maxRows) {
@@ -518,7 +525,60 @@ var SQLServerConnector = class _SQLServerConnector {
       throw new Error(`Failed to execute query: ${error.message}`);
     }
   }
+  /**
+   * Return the estimated execution plan for a query using SHOWPLAN_XML.
+   *
+   * SHOWPLAN_XML compiles the statement and returns its plan without executing
+   * it, but it has two constraints: `SET SHOWPLAN_XML ON` must be the only
+   * statement in its batch, and the setting is session scoped. The shared pool
+   * hands out a fresh connection per request() and an open transaction
+   * suppresses SHOWPLAN, so neither can carry the setting to a follow-up query.
+   *
+   * We therefore run the SET / query pair on a short-lived, single-connection
+   * pool built from the same config. The dedicated session keeps SHOWPLAN state
+   * off the shared pool, so a concurrent query can never land on a connection
+   * with SHOWPLAN enabled (which would return a plan instead of its results).
+   */
+  async explainQuery(innerQuery) {
+    const cleaned = stripCommentsAndStrings(innerQuery, "sqlserver").trim();
+    if (!cleaned) {
+      throw new Error("EXPLAIN requires a statement to analyze");
+    }
+    if (/\bset\s+showplan/i.test(cleaned)) {
+      throw new Error("EXPLAIN does not support SET SHOWPLAN statements");
+    }
+    if (!this.config) {
+      throw new Error("Not connected to SQL Server database");
+    }
+    const explainPool = new sql.ConnectionPool({
+      ...this.config,
+      pool: { ...this.config.pool, max: 1, min: 1 }
+    });
+    try {
+      await explainPool.connect();
+      await explainPool.request().batch("SET SHOWPLAN_XML ON");
+      const planResult = await explainPool.request().batch(innerQuery);
+      const planRow = planResult.recordset?.[0];
+      const planXml = planRow ? Object.values(planRow)[0] : null;
+      return {
+        rows: planXml != null ? [{ plan: planXml }] : [],
+        rowCount: planXml != null ? 1 : 0
+      };
+    } catch (error) {
+      throw new Error(`Failed to explain query: ${error.message}`);
+    } finally {
+      await explainPool.close();
+    }
+  }
 };
+/**
+ * Leading whitespace and SQL comments to skip before looking for a keyword.
+ * The read-only validator strips comments before checking the first keyword,
+ * so the connector must skip them too; otherwise an EXPLAIN preceded by a
+ * comment passes validation but reaches the server untranslated.
+ */
+_SQLServerConnector.LEADING_NOISE = /^(?:\s+|--[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/)*/;
+var SQLServerConnector = _SQLServerConnector;
 var sqlServerConnector = new SQLServerConnector();
 ConnectorRegistry.register(sqlServerConnector);
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytebase/dbhub",
-  "version": "0.22.2",
+  "version": "0.22.4",
   "mcpName": "io.github.bytebase/dbhub",
   "description": "Minimal, token-efficient Database MCP Server for PostgreSQL, MySQL, SQL Server, SQLite, MariaDB",
   "repository": {