@bytebase/dbhub 1.0.0 → 1.2.0

package/README.md

@@ -1,5 +1,5 @@
 > [!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://dbhub.ai/" target="_blank">
@@ -30,9 +30,9 @@
                  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 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:
 
-- **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): 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,61 +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.
-
-**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
-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`.
->
-> 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.
-
-### 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-MQR6VX5F.js → chunk-CUBIR72I.js}

@@ -8,15 +8,22 @@ import {
   getDefaultPortForType,
   parseConnectionInfoFromDSN,
   stripCommentsAndStrings
-} from "./chunk-JEZZN2YZ.js";
+} from "./chunk-WIQ4DWGY.js";
 
 // 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";
@@ -798,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);
@@ -1130,7 +1152,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 +2300,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 +2372,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(", ")}`
         );
       }
     }
@@ -2485,9 +2507,12 @@ export {
   resolvePort,
   resolveHost,
   resolveAllowedHosts,
+  resolveAuthTokens,
   resolveSourceConfigs,
   BUILTIN_TOOL_EXECUTE_SQL,
   BUILTIN_TOOL_SEARCH_OBJECTS,
+  BUILTIN_TOOL_EXPLAIN_SQL,
+  BUILTIN_TOOL_HEALTH_CHECK,
   loadTomlConfig,
   resolveTomlConfigPath,
   classifyConnectionError,

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-JO7YQPBQ.js → chunk-PBN2UXB5.js}

@@ -1,6 +1,6 @@
 import {
   stripCommentsAndStrings
-} from "./chunk-JEZZN2YZ.js";
+} from "./chunk-WIQ4DWGY.js";
 
 // src/utils/allowed-keywords.ts
 var allowedKeywords = {
@@ -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-QEFMUQJ2.js

@@ -0,0 +1,179 @@
+import {
+  computeHitRatioPct,
+  toNullableNumber
+} from "./chunk-FU2ZJE4E.js";
+import {
+  obfuscateDSNPassword
+} from "./chunk-WIQ4DWGY.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 buildResultSetsFromMultiStatement(results, statementTexts) {
+  const sql = statementTexts?.length === results.length ? statementTexts : void 0;
+  return results.map((result, index) => {
+    if (Array.isArray(result)) {
+      return { sql: sql?.[index], rows: result, rowCount: result.length };
+    }
+    if (isMetadataObject(result)) {
+      return { sql: sql?.[index], rows: [], rowCount: result.affectedRows || 0 };
+    }
+    return { sql: sql?.[index], rows: [], rowCount: 0 };
+  });
+}
+function parseQueryResultSets(results, statementTexts) {
+  const singleStatementSql = statementTexts?.length === 1 ? statementTexts[0] : void 0;
+  if (isMetadataObject(results)) {
+    return [{ sql: singleStatementSql, rows: [], rowCount: results.affectedRows || 0 }];
+  }
+  if (!Array.isArray(results)) {
+    return [{ sql: singleStatementSql, rows: [], rowCount: 0 }];
+  }
+  if (isMultiStatementResult(results)) {
+    return buildResultSetsFromMultiStatement(results, statementTexts);
+  }
+  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();
+  }
+  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) {
+    if (!isClientSideTimeout(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,
+  parseQueryResultSets,
+  isClientSideTimeout,
+  withReadOnlyTransaction,
+  isTiDBVersion
+};

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

@@ -1,6 +1,7 @@
 import {
+  blankCommentsAndStrings,
   stripCommentsAndStrings
-} from "./chunk-JEZZN2YZ.js";
+} from "./chunk-WIQ4DWGY.js";
 
 // src/utils/sql-row-limiter.ts
 var SQLRowLimiter = class {
@@ -70,17 +71,77 @@ var SQLRowLimiter = class {
 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}`);
-    } else {
-      return sql.replace(/\bselect\s+/i, `SELECT TOP ${maxRows} `);
     }
+    return sql.replace(/\bselect\s+/i, `SELECT TOP ${maxRows} `);
   }
   /**
    * Check if a LIMIT clause uses a parameter placeholder (not a literal number).

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

@@ -462,6 +462,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 +510,6 @@ export {
   getDatabaseTypeFromDSN,
   getDefaultPortForType,
   stripCommentsAndStrings,
+  blankCommentsAndStrings,
   splitSQLStatements
 };