dsh-db-tool 1.7.1 → 1.8.0

package/dist/adapters/sqlserver/index.js

@@ -0,0 +1,840 @@
+/**
+ * SQL Server 适配器（SQL Server 2008/2008 R2 – 2022 与 Azure SQL；mssql@12，底层 tedious 纯 JS TDS）。
+ *
+ * 驱动加载：mssql 只在 devDependencies。它是唯一会把 buffer/events/process/string_decoder
+ * 四个核心模块同名包带进生产依赖树的驱动（mssql → tedious → bl → readable-stream），
+ * 会触发宿主 @deepseek-ai/dsh-app-boot 的 require.resolve.paths bug 使插件整体加载失败
+ * （约束由 tests/guard/deps-core-collision.spec.ts 守护）。故运行时经 createRequire 相对
+ * 加载 vendor/sqlserver-driver.cjs（scripts/build-sqlserver.mjs 产物），失败不缓存并给中文
+ * 修复指引。mssql 12.7.4 不随包发 .d.ts（package.json 无 types 字段），类型在本文件自声明
+ * 最小接口——与 pg-like.ts 的 PgLikeDriver 同一手法。
+ *
+ * 占位符：对外只接受 `?`（客户端 dialectOf('sqlserver') 返回 'q'），内部经词法扫描顺序重写为
+ * `@p1..@pN` 并 request.input('pN', v)。扫描跳过单引号串（含 N'...' 与 '' 转义）、[方括号]、
+ * "双引号"、行注释（--）与块注释内的 `?`；个数与 params 不一致即抛中文错误。
+ *
+ * 版本降级：SERVERPROPERTY('ProductMajorVersion') 探测（NULL 时回退 ProductVersion 前缀），
+ * 按池缓存。>=11（2012+，含 Azure SQL 的 12）用 OFFSET/FETCH（T-SQL 强制要求 ORDER BY，
+ * 用常量排序 ORDER BY (SELECT NULL) 保持「不指定顺序」的语义）；<11（2008/2008 R2）降级为
+ * ROW_NUMBER() OVER (...) 子查询，并把内部序号列从结果集中剔除。
+ *
+ * 只读(ro)语义诚实降级：SQL Server 没有等价的会话级只读语句（不像 MySQL 的
+ * SET SESSION TRANSACTION READ ONLY 或 PG 的 SET SESSION CHARACTERISTICS AS TRANSACTION
+ * READ ONLY），无法在服务器侧强制只读。故 ro 强度弱于 mysql/pg，只有三层：
+ * 服务层拦 execute + 适配器侧 query 首词白名单（复用 guard 的 SQL_READ_HEADS）+
+ * 拒绝多语句（防 `SELECT 1; UPDATE ...` 堆叠写）。这里是应用层防线，不是服务器级保证。
+ */
+import { createRequire } from 'node:module';
+import { SQL_READ_HEADS, sqlHead } from '../../guard/index.js';
+import { assertIdent, clampLimit, clampOffset, humanize, normalizeCell } from '../sql-shared/common.js';
+let vendorCache;
+/** 容错加载 vendor bundle：缺失返回 undefined，成功后缓存；失败不缓存 → 构建完成即可恢复 */
+function vendorOrNull() {
+    if (vendorCache === undefined) {
+        try {
+            // 相对路径从本模块出发：dist/adapters/sqlserver/ 或 lib/adapters/sqlserver/ 均指向包根 vendor/
+            vendorCache = createRequire(import.meta.url)('../../../vendor/sqlserver-driver.cjs');
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return vendorCache;
+}
+/** 严格加载：缺失时抛带修复指引的中文错误 */
+function vendor() {
+    const m = vendorOrNull();
+    if (m === undefined) {
+        throw new Error('sqlserver 驱动不可用：缺少 vendor/sqlserver-driver.cjs。请在插件目录运行 npm run build:sqlserver 构建后重试');
+    }
+    return m;
+}
+/* ============================ 配置解析 ============================ */
+/** tedious 支持的 TDS 协议版本（默认 7_4） */
+const TDS_VERSIONS = new Set(['7_4', '7_3_A', '7_3_B', '7_2', '7_1']);
+/** URLSearchParams 取值（参数名大小写不敏感，URL 里常见 camelCase 与全小写混写） */
+function queryParam(sp, name) {
+    const lower = name.toLowerCase();
+    for (const [k, v] of sp) {
+        if (k.toLowerCase() === lower)
+            return v;
+    }
+    return undefined;
+}
+/** 布尔 query 参数：非法值抛中文错误而非静默回退（连错加密策略是安全事故） */
+function boolParam(sp, name, dflt) {
+    const v = queryParam(sp, name);
+    if (v === undefined || v === '')
+        return dflt;
+    const s = v.trim().toLowerCase();
+    if (s === 'true' || s === '1' || s === 'yes')
+        return true;
+    if (s === 'false' || s === '0' || s === 'no')
+        return false;
+    throw new Error(`sqlserver 连接 URL 的 ${name} 取值非法：${JSON.stringify(v)}（只接受 true/false）`);
+}
+function decodeCred(raw) {
+    try {
+        return decodeURIComponent(raw);
+    }
+    catch {
+        throw new Error('sqlserver 连接 URL 的用户名或密码 percent 编码非法（如含未编码的 %），请 URL 编码后重试');
+    }
+}
+function validPort(v, dflt) {
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 && n <= 65535 ? Math.floor(n) : dflt;
+}
+/**
+ * URL 脱敏（错误消息可能进 audit.jsonl 与模型上下文，绝不能回显明文密码）：
+ * 保留 scheme 与 host(:port)，userinfo 一律替换为 ***，query/fragment 丢弃。
+ * 纯文本处理、不依赖 WHATWG URL —— 本函数正是在 new URL() 失败时使用。
+ */
+function redactUrl(url) {
+    const schemeEnd = url.indexOf('://');
+    const head = schemeEnd >= 0 ? url.slice(0, schemeEnd + 3) : '';
+    const rest = url.slice(head.length);
+    const authEnd = /[/?#]/.exec(rest)?.index ?? rest.length;
+    const authority = rest.slice(0, authEnd);
+    const at = authority.lastIndexOf('@');
+    const host = at >= 0 ? authority.slice(at + 1) : authority;
+    return `${head}${at >= 0 ? '***@' : ''}${host}`;
+}
+/** ResolvedConnection → mssql 池配置（浏览适配器与传输端共用，保证连接语义一致） */
+function poolConfig(conn) {
+    const options = {
+        encrypt: true,
+        trustServerCertificate: false,
+        tdsVersion: '7_4',
+        useUTC: true,
+    };
+    const cfg = { options };
+    if (conn.url) {
+        let u;
+        try {
+            u = new URL(conn.url);
+        }
+        catch {
+            // 脱敏：错误消息会进 audit.jsonl 与模型上下文，绝不回显 userinfo 明文密码
+            throw new Error(`sqlserver 连接 URL 无法解析：${redactUrl(conn.url)}（期望形态 sqlserver://user:pass@host:1433/db?encrypt=true；请检查端口是否在 1-65535、是否有多余字符）`);
+        }
+        if (!u.hostname)
+            throw new Error('sqlserver 连接 URL 缺少主机名（期望形态 sqlserver://user:pass@host:1433/db）');
+        cfg.server = u.hostname;
+        cfg.port = u.port ? validPort(u.port, 1433) : 1433;
+        if (u.username)
+            cfg.user = decodeCred(u.username);
+        if (u.password)
+            cfg.password = decodeCred(u.password);
+        const path = u.pathname.replace(/^\//, '');
+        if (path)
+            cfg.database = decodeCred(path);
+        options.encrypt = boolParam(u.searchParams, 'encrypt', true);
+        options.trustServerCertificate = boolParam(u.searchParams, 'trustServerCertificate', false);
+        options.useUTC = boolParam(u.searchParams, 'useUTC', true);
+        const tds = queryParam(u.searchParams, 'tdsVersion');
+        if (tds !== undefined && tds !== '') {
+            if (!TDS_VERSIONS.has(tds)) {
+                throw new Error(`sqlserver 连接 URL 的 tdsVersion 取值非法：${JSON.stringify(tds)}（可选 ${[...TDS_VERSIONS].join('/')}，默认 7_4）`);
+            }
+            options.tdsVersion = tds;
+        }
+        const instance = queryParam(u.searchParams, 'instanceName');
+        // 指定命名实例时 tedious 会忽略 port，改由 SQL Server Browser（UDP 1434）解析
+        if (instance !== undefined && instance !== '')
+            options.instanceName = instance;
+        // fields.database 覆盖 URL 库名：传输端跨库定位（sqlserverLocate）按 pg/mysql 惯例、
+        // 用浅拷贝在 fields 上写 database 而不改写 URL——此处让该覆盖生效，避免静默连回原库。
+        const fdb = conn.fields?.['database'];
+        if (fdb != null && String(fdb) !== '')
+            cfg.database = String(fdb);
+    }
+    else if (conn.fields) {
+        const f = conn.fields;
+        cfg.server = String(f.host ?? 'localhost');
+        cfg.port = validPort(f.port, 1433);
+        if (f.user != null && String(f.user) !== '')
+            cfg.user = String(f.user);
+        else if (f.username != null && String(f.username) !== '')
+            cfg.user = String(f.username);
+        if (f.password != null)
+            cfg.password = String(f.password);
+        if (f.database != null && String(f.database) !== '')
+            cfg.database = String(f.database);
+        if (f.instanceName != null && String(f.instanceName) !== '')
+            options.instanceName = String(f.instanceName);
+    }
+    else {
+        throw new Error('sqlserver 连接缺少 url 或 fields 配置');
+    }
+    // conn.ssl 是通用字段（mysql/pg 适配器同样处理）：语义上等价要求加密信道
+    if (conn.ssl)
+        options.encrypt = true;
+    cfg.connectionTimeout = 15000;
+    cfg.requestTimeout = 30000;
+    cfg.pool = { max: 10, min: 0, idleTimeoutMillis: 30000 };
+    return cfg;
+}
+function resolveDatabase(conn) {
+    if (conn.fields && conn.fields.database != null && String(conn.fields.database) !== '') {
+        return String(conn.fields.database);
+    }
+    if (conn.url) {
+        const p = new URL(conn.url).pathname.replace(/^\//, '');
+        if (p)
+            return decodeCred(p);
+    }
+    return undefined;
+}
+/** T-SQL token 字符（标识符/关键字/变量名；`@` `#` `$` 均可在标识符内） */
+const WORD_CHAR = /[A-Za-z0-9_@$#]/;
+/**
+ * 单遍词法扫描：识别并跳过字符串/标识符/注释，统计顶层 `?`、顶层 token 与顶层分号。
+ * 跳过规则（T-SQL 词法）：
+ *  - '...'：单引号串（N'...' 的 N 是普通字符，无需特殊处理），内部 '' 为转义；
+ *  - [..]：方括号标识符，内部 ]] 为转义；
+ *  - "..."：双引号（QUOTED_IDENTIFIER ON 下是标识符），内部 "" 为转义；
+ *  - -- 行注释（到行尾）、块注释。
+ * 已知边界（不实现，保持失败可见）：T-SQL 允许嵌套块注释（块注释里再开一个块注释），
+ * 本扫描器按首个注释结束符收尾 → 会把注释里剩余的 `?` 计入占位符，最终报「个数不一致」
+ * （fail-closed，不会误放行；提示文案可能略显跳脱）。需要精确支持时再扩展为深度计数。
+ */
+function scanSql(sql) {
+    const placeholders = [];
+    const words = [];
+    let hasNamedParam = false;
+    let multi = false;
+    let sawSemi = false;
+    let i = 0;
+    const n = sql.length;
+    while (i < n) {
+        const ch = sql[i];
+        // 注释与空白整体跳过：它们不构成语句，也不参与「分号之后是否还有语句」的判定
+        if (ch === '-' && sql[i + 1] === '-') {
+            i += 2;
+            while (i < n && sql[i] !== '\n')
+                i++;
+            continue;
+        }
+        if (ch === '/' && sql[i + 1] === '*') {
+            i += 2;
+            while (i < n && !(sql[i] === '*' && sql[i + 1] === '/'))
+                i++;
+            i = Math.min(n, i + 2);
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            i++;
+            continue;
+        }
+        // 多语句判定必须先于各跳过分支：顶层分号之后只要还有任何内容（word / `?` / 标点 / 字符串起手），
+        // 就是第二条语句。原实现把该判定放在循环末尾、且被 word 分支的 continue 绕过 —— 于是
+        // `SELECT 1;DROP TABLE t`、`SELECT 1;EXEC xp_cmdshell 'x'` 这类「第二条全为标识符」的堆叠写被放行。
+        if (sawSemi)
+            multi = true;
+        if (ch === "'" || ch === '"') {
+            i++;
+            while (i < n) {
+                if (sql[i] === ch) {
+                    if (sql[i + 1] === ch) {
+                        i += 2;
+                        continue;
+                    }
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        if (ch === '[') {
+            i++;
+            while (i < n) {
+                if (sql[i] === ']') {
+                    if (sql[i + 1] === ']') {
+                        i += 2;
+                        continue;
+                    }
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        if (ch === '-' && sql[i + 1] === '-') {
+            i += 2;
+            while (i < n && sql[i] !== '\n')
+                i++;
+            continue;
+        }
+        if (ch === '/' && sql[i + 1] === '*') {
+            i += 2;
+            while (i < n && !(sql[i] === '*' && sql[i + 1] === '/'))
+                i++;
+            i = Math.min(n, i + 2);
+            continue;
+        }
+        if (WORD_CHAR.test(ch)) {
+            let j = i + 1;
+            while (j < n && WORD_CHAR.test(sql[j]))
+                j++;
+            const tok = sql.slice(i, j).toLowerCase();
+            words.push(tok);
+            // 只认精确的 @p1/@P1 形态（T-SQL 变量名大小写不敏感）：@p1x、@p、@@p1 都是普通标识符/系统变量，
+            // 把它们当占位符会误报「混用」，让用户无法使用以 @p 开头的变量名。
+            if (/^@p\d+$/i.test(tok))
+                hasNamedParam = true;
+            i = j;
+            continue;
+        }
+        if (ch === '?')
+            placeholders.push(i);
+        else if (ch === ';')
+            sawSemi = true;
+        i++;
+    }
+    return { placeholders, words, multi, hasNamedParam };
+}
+/** 占位符/参数一致性校验（在建池建请求之前调用：参数写错不该先触发网络 IO） */
+function assertPlaceholderCount(scan, params) {
+    // 混用会让 @pN 之外的位置也被绑定成同一个参数（静默错值），必须直接拒绝
+    if (scan.hasNamedParam && scan.placeholders.length > 0) {
+        throw new Error('不允许在同一条语句中混用 ? 与 @pN 占位符：请统一使用 ?（适配器会自动重写为 @p1..@pN 并按顺序绑定）');
+    }
+    if (scan.placeholders.length !== params.length) {
+        throw new Error(`SQL 中 ? 占位符个数(${scan.placeholders.length})与传入参数个数(${params.length})不一致：请补齐/减少参数以匹配 ? 的个数` +
+            '（本适配器只接受 ? 占位符并自动重写为 @pN 绑定，不支持在 SQL 里直接写 @pN 再单独传参）');
+    }
+}
+/** 把顶层 `?` 顺序重写为 @p1..@pN 并绑定到 request（调用前须已 assertPlaceholderCount） */
+function rewritePlaceholders(req, sql, scan, params) {
+    let out = '';
+    let prev = 0;
+    scan.placeholders.forEach((pos, idx) => {
+        out += sql.slice(prev, pos) + `@p${idx + 1}`;
+        prev = pos + 1;
+    });
+    out += sql.slice(prev);
+    params.forEach((v, idx) => req.input(`p${idx + 1}`, v));
+    return out;
+}
+/**
+ * ro 模式下 query 的只读闸门（应用层防线，见文件头注释）：
+ *  1) 首词白名单（SQL_READ_HEADS）；
+ *  2) 拒绝多语句；
+ *  3) SQL Server 专属写形态——通用 guard 遮不住的三类，而 SQL Server 没有服务器级只读可兜底：
+ *     - `SELECT ... INTO <目标>`：无确认建表并复制数据（guard 的 into 只匹配 MySQL 的 OUTFILE/DUMPFILE）；
+ *     - `WITH ... INSERT|UPDATE|DELETE|MERGE`：CTE 直接跟写语句（guard 的 writeBody 能识别，但 ro 只查首词）；
+ *     - `OPENQUERY(...)/OPENROWSET(...)/OPENDATASOURCE(...)`：其字符串参数在远端/外部数据源执行任意语句
+ *       （含写与 xp_cmdshell），ro 连接上无法审计其内容，一律拒绝（保守：只读场景罕见，误拒代价远小于放行写）。
+ *  所有判定都走 scanSql 的顶层 token（已跳过字符串/方括号/双引号标识符/注释），
+ *  因此字符串里的 into、方括号标识符（如 [into]）、以及块注释里的 into 都不会误伤。
+ *  局限（安全取舍）：裸标识符恰好叫 into/delete 等保留字的极端场景会被误拒（fail-closed）。
+ */
+function assertReadOnlyQuery(sql, scan) {
+    if (!SQL_READ_HEADS.has(sqlHead(sql))) {
+        throw new Error('DRIVER_ERROR: 只读(ro)模式下 query 仅允许读语句（select/with/show/describe/desc/explain/use/set/help/table），写操作请使用可写连接');
+    }
+    if (scan.multi) {
+        throw new Error('DRIVER_ERROR: 只读(ro)模式下 query 不允许一次提交多条语句（分号后仍有语句），请拆分为独立查询');
+    }
+    const words = new Set(scan.words);
+    if (words.has('into')) {
+        throw new Error('DRIVER_ERROR: 只读(ro)模式下不允许 SELECT ... INTO（会创建新表并复制数据），请使用可写连接');
+    }
+    if (scan.words[0] === 'with' &&
+        (words.has('insert') || words.has('update') || words.has('delete') || words.has('merge'))) {
+        throw new Error('DRIVER_ERROR: 只读(ro)模式下不允许 WITH 子句后跟写操作（insert/update/delete/merge），请使用可写连接');
+    }
+    if (words.has('openquery') || words.has('openrowset') || words.has('opendatasource')) {
+        throw new Error('DRIVER_ERROR: 只读(ro)模式下不允许 OPENQUERY/OPENROWSET/OPENDATASOURCE（其字符串参数会在远端/外部数据源执行任意语句，无法审计），请使用可写连接');
+    }
+}
+function errText(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/**
+ * mssql 错误码 → 中文可读提示。ETIMEOUT 在 ConnectionError（建连超时）与 RequestError
+ * （语句执行超时）下语义不同，故结合 err.name 判断而非只看 code；originalError/precedingErrors
+ * 附加在末尾用于追溯。无法识别时保留原始 message（不吞信息）。
+ */
+function mssqlReason(e) {
+    const err = (e ?? {});
+    const code = typeof err.code === 'string' ? err.code : '';
+    const name = typeof err.name === 'string' ? err.name : '';
+    const detail = typeof err.message === 'string' ? err.message : String(e);
+    const num = typeof err.number === 'number' ? err.number : undefined;
+    const sev = typeof err.severity === 'number' ? err.severity : undefined;
+    const line = typeof err.lineNumber === 'number' ? err.lineNumber : undefined;
+    // TLS/证书类失败（自签证书、链不可验证、协议版本不符）在 SQL Server 2008/2008 R2 上很常见。
+    // 默认 encrypt=true + trustServerCertificate=false 与 mssql 官方一致（不改默认值），但必须：
+    //  1) 不把「TCP 已连通、TLS 校验失败」误报成网络不可达（会把用户引向错误排查方向）；
+    //  2) 把「怎么连上」写清楚（URL 加 ?trustServerCertificate=true / ?encrypt=false）。
+    const tlsText = `${detail} ${errText(err.originalError)}`;
+    const tlsish = /self[ -]?signed|certificate|unable to verify|wrong version number|ERR_SSL|EPROTO|CERT_/i.test(tlsText);
+    let base;
+    switch (code) {
+        case 'ELOGIN':
+            base = `登录失败：用户名或密码错误，或账号不允许从当前主机登录（${detail}）`;
+            break;
+        case 'ETIMEOUT':
+            base =
+                name === 'ConnectionError'
+                    ? `连接超时：未能在超时时间内建立连接，请检查主机/端口/防火墙（${detail}）`
+                    : `请求超时：语句执行超过 requestTimeout，请拆小查询或调大超时（${detail}）`;
+            break;
+        case 'ESOCKET':
+            // 保留「网络不可达」字样（既有断言与用户检索习惯依赖），但 TLS 特征时先说明 TCP 已连通
+            base = tlsish
+                ? `TCP 已连通但 TLS 握手/证书校验失败（不是网络不可达：网络不可达指主机/端口不可达或连接被拒，此处 TCP 已建立）（${detail}）`
+                : `网络不可达：无法与服务器建立 TCP 连接，请检查主机名、端口与网络（${detail}）`;
+            break;
+        // 服务器强制加密（SQL Server 2022 / Azure SQL 默认）而客户端 encrypt=false：tedious 抛英文原文，
+        // 不映射则中文界面里只剩英文，故单列一条给出可直接照做的改法。
+        case 'EENCRYPT':
+            base = `服务器要求加密连接：当前 encrypt=false 被服务器拒绝，请改用 ?encrypt=true 后重试（${detail}）`;
+            break;
+        case 'EINSTLOOKUP':
+            base = `实例名解析失败：SQL Server Browser 服务可能未运行或 UDP 1434 不可达（命名实例可改用「主机:端口」直连，如 host,1433）（${detail}）`;
+            break;
+        case 'ENOTOPEN':
+        case 'ECONNCLOSED':
+            base = `连接已关闭或未打开：请重新连接后重试（${detail}）`;
+            break;
+        case 'ECANCEL':
+            base = `请求已取消（${detail}）`;
+            break;
+        case 'EREQUEST':
+            base = `SQL 执行错误${num !== undefined ? `（错误号 ${num}${sev !== undefined ? `、严重级 ${sev}` : ''}${line !== undefined ? `、第 ${line} 行` : ''}）` : ''}：${detail}`;
+            break;
+        default:
+            base = detail;
+    }
+    const trail = [];
+    if (tlsish) {
+        trail.push('若目标是 SQL Server 2008/2008 R2 或使用自签名证书的实例，可在连接 URL 追加 ?trustServerCertificate=true（或 ?encrypt=false，前提是服务器未强制加密）');
+    }
+    if (err.originalError !== undefined)
+        trail.push(`原始错误: ${errText(err.originalError)}`);
+    if (Array.isArray(err.precedingErrors) && err.precedingErrors.length > 0) {
+        trail.push(`前序错误: ${err.precedingErrors.map(errText).join('; ')}`);
+    }
+    return trail.length > 0 ? `${base}。${trail.join('；')}` : base;
+}
+/** 映射错误并把结构化信息（code/number/…）透传给上层，便于日志与守卫判断 */
+function mappedError(e) {
+    const err = e instanceof Error ? e : new Error(String(e));
+    const reason = mssqlReason(e);
+    const out = new Error(reason);
+    out.name = err.name;
+    const src = err;
+    Object.assign(out, {
+        code: src.code,
+        number: src.number,
+        severity: src.severity,
+        lineNumber: src.lineNumber,
+        originalError: err,
+    });
+    return out;
+}
+/** humanize + 错误码映射的组合包装 */
+function wrap(label, fn) {
+    return humanize(label, async () => {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            throw mappedError(e);
+        }
+    });
+}
+/* ============================ 类型规范化 ============================ */
+/** 字符/二进制类（max_length 即字符数）；N 前缀类型 max_length 是字节数（2 倍字符数） */
+const CHAR_TYPES = new Set(['char', 'varchar', 'binary', 'varbinary']);
+const NCHAR_TYPES = new Set(['nchar', 'nvarchar']);
+const DECIMAL_TYPES = new Set(['decimal', 'numeric']);
+const SCALED_TYPES = new Set(['datetime2', 'datetimeoffset', 'time']);
+function formatDataType(name, maxLength, precision, scale) {
+    const t = name.toLowerCase();
+    if (CHAR_TYPES.has(t) || NCHAR_TYPES.has(t)) {
+        if (maxLength < 0)
+            return `${name}(max)`;
+        const len = NCHAR_TYPES.has(t) ? Math.floor(maxLength / 2) : maxLength;
+        return `${name}(${len})`;
+    }
+    if (DECIMAL_TYPES.has(t))
+        return `${name}(${precision}, ${scale})`;
+    if (SCALED_TYPES.has(t))
+        return `${name}(${scale})`;
+    return name;
+}
+/** 版本探测 SQL（ProductMajorVersion 为 NULL 时用 ProductVersion 前缀回退） */
+const VERSION_SQL = `SELECT CAST(SERVERPROPERTY('ProductMajorVersion') AS int) AS major,
+       CAST(SERVERPROPERTY('ProductVersion') AS nvarchar(128)) AS version`;
+function parseMajor(row) {
+    const m = row?.['major'];
+    if (typeof m === 'number' && Number.isFinite(m) && m >= 1)
+        return m;
+    const v = row?.['version'];
+    if (typeof v === 'string') {
+        const p = Number.parseInt(v, 10);
+        if (Number.isFinite(p) && p >= 1)
+            return p;
+    }
+    return 0; // 探测失败按 <11 降级（ROW_NUMBER 在任意版本可用，保证能出结果）
+}
+/* ============================ 池包装 ============================ */
+/** 结果行视图（元素形态在类型上放宽为 unknown，读取时统一按 Record 处理） */
+function rowsOf(res) {
+    return (res.recordset ?? res.recordsets?.[0] ?? []);
+}
+function makePoolBox(Driver, cfg) {
+    const pool = new Driver.ConnectionPool(cfg);
+    // 无条件兜底：mssql 的 ConnectionPool 在 acquire 失败（空闲连接被服务器断开等）时会
+    // emit('error', err)，EventEmitter 无监听器时直接抛 → 崩掉宿主进程。
+    pool.on('error', () => { });
+    let connecting;
+    const ready = () => {
+        if (connecting === undefined) {
+            connecting = Promise.resolve(pool.connect()).then(() => undefined, (e) => {
+                connecting = undefined; // 失败不缓存：允许下次重试
+                throw e;
+            });
+        }
+        return connecting;
+    };
+    let majorPromise;
+    const major = () => {
+        if (majorPromise === undefined) {
+            // 探测失败（SERVERPROPERTY 不可用 / 无权限 / 网络抖动）一律按 0 → 走 ROW_NUMBER 降级路径：
+            // 探测本身不该把整个 previewRows 打挂，ROW_NUMBER 在任意版本都可用（与传输端 propOf 的容错对称）。
+            majorPromise = (async () => {
+                try {
+                    await ready();
+                    const res = await pool.request().query(VERSION_SQL);
+                    return parseMajor(rowsOf(res)[0]);
+                }
+                catch {
+                    return 0;
+                }
+            })();
+        }
+        return majorPromise;
+    };
+    return { pool, ready, major };
+}
+/* ============================ 适配器 ============================ */
+const LIST_DATABASES_SQL = `SELECT name FROM sys.databases WHERE database_id > 4 ORDER BY name`;
+// 系统 schema 过滤：guest/sys/INFORMATION_SCHEMA 与固定数据库角色 schema（schema_id >= 16384）
+const LIST_SCHEMAS_SQL = `SELECT s.name AS name FROM sys.schemas s
+ WHERE s.name NOT IN ('guest', 'sys', 'INFORMATION_SCHEMA') AND s.schema_id < 16384
+ ORDER BY s.name`;
+// sys.objects 同时覆盖表(U)与视图(V)；is_ms_shipped 排除系统附带对象
+const LIST_TABLES_SQL = `SELECT o.name AS table_name, o.type AS obj_type
+ FROM sys.objects o JOIN sys.schemas s ON s.schema_id = o.schema_id
+ WHERE s.name = @p1 AND o.type IN ('U', 'V') AND o.is_ms_shipped = 0
+ ORDER BY o.name`;
+// 元数据一律用 object_id/column_id 整数键关联（避免 collation/大小写差异）；
+// 扩展属性 MS_Description 作列注释（2005+ 通用写法，无 STRING_AGG/CONCAT_WS 等新语法）
+const DESCRIBE_COLUMNS_SQL = `SELECT c.column_id, c.name AS column_name, t.name AS type_name,
+        c.max_length, c.precision, c.scale, c.is_nullable,
+        dc.definition AS default_def, ep.value AS comment
+ FROM sys.columns c
+ JOIN sys.types t ON t.user_type_id = c.user_type_id
+ LEFT JOIN sys.default_constraints dc ON dc.parent_object_id = c.object_id AND dc.parent_column_id = c.column_id
+ LEFT JOIN sys.extended_properties ep ON ep.class = 1 AND ep.major_id = c.object_id AND ep.minor_id = c.column_id AND ep.name = N'MS_Description'
+ WHERE c.object_id = OBJECT_ID(@p1)
+ ORDER BY c.column_id`;
+const DESCRIBE_PK_SQL = `SELECT ic.column_id
+ FROM sys.indexes i JOIN sys.index_columns ic ON ic.object_id = i.object_id AND ic.index_id = i.index_id
+ WHERE i.object_id = OBJECT_ID(@p1) AND i.is_primary_key = 1`;
+const TEST_CONNECT_SQL = `SELECT CAST(SERVERPROPERTY('ProductVersion') AS nvarchar(128)) AS version,
+       CAST(SERVERPROPERTY('ProductMajorVersion') AS int) AS major,
+       CAST(SERVERPROPERTY('EngineEdition') AS int) AS engine`;
+const PRODUCT_NAMES = {
+    9: '2005',
+    10: '2008',
+    11: '2012',
+    12: '2014',
+    13: '2016',
+    14: '2017',
+    15: '2019',
+    16: '2022',
+};
+/** 版本串展示：'Microsoft SQL Server 2019 - 15.0.2000.5'（Azure SQL 按 EngineEdition=5 单独标注） */
+function serverInfo(version, major, engine) {
+    if (engine === 5)
+        return `Azure SQL Database - ${version}`;
+    const m = typeof major === 'number' ? major : Number.parseInt(version, 10);
+    let name = PRODUCT_NAMES[m];
+    if (m === 10 && version.startsWith('10.5'))
+        name = '2008 R2';
+    return `Microsoft SQL Server ${name ?? m} - ${version}`;
+}
+export async function createSqlserverAdapter(conn, opts) {
+    // 配置先于驱动解析：配置错误不依赖 vendor 是否构建，用户能立刻拿到正确指引
+    const cfg = poolConfig(conn);
+    const Driver = opts?.driver ?? vendor();
+    const readOnly = opts?.mode === 'ro';
+    const mainDb = resolveDatabase(conn);
+    // 类型钉死：decimal/numeric/bigint/uniqueidentifier 一律转字符串。SQL Server 官方类型表里
+    // decimal/numeric 返回 JS Number、bigint 返回 Number/String，超过 2^53 会静默丢精度；
+    // 注意驱动在解析阶段已按数值解析过（精度损失发生在 tedious 内部），此处只能防止后续
+    // 再被当数值处理——需要逐位保真的场景请在 SQL 里显式 CONVERT(nvarchar(...), col)。
+    const TYPES = Driver.TYPES ?? {};
+    const pinnedTypes = new Set([TYPES['Decimal'], TYPES['Numeric'], TYPES['BigInt'], TYPES['UniqueIdentifier']].filter((t) => t !== undefined));
+    const cellOf = (v, meta) => {
+        if (v === null || v === undefined)
+            return null;
+        if (meta?.type !== undefined && pinnedTypes.has(meta.type)) {
+            return typeof v === 'string' ? v : typeof v === 'bigint' ? v.toString() : String(v);
+        }
+        return normalizeCell(v);
+    };
+    const toQueryResult = (res, dropColumns) => {
+        const recordset = (res.recordset ?? res.recordsets?.[0] ?? []);
+        const meta = recordset.columns;
+        const first = recordset[0];
+        let names = meta ? Object.keys(meta) : first ? Object.keys(first) : [];
+        if (dropColumns && dropColumns.length > 0) {
+            const drop = new Set(dropColumns.map((c) => c.toLowerCase()));
+            names = names.filter((c) => !drop.has(c.toLowerCase()));
+        }
+        const rows = recordset.map((r) => {
+            const row = r;
+            return names.map((c) => cellOf(row[c], meta?.[c]));
+        });
+        return { columns: names, rows, rowCount: rows.length };
+    };
+    const mainPool = makePoolBox(Driver, cfg);
+    // 跨库（Navicat 式）：按库名缓存独立池，ro 时同样受首词白名单约束（query 路径统一校验）。
+    /**
+     * 关闭幂等标志：manager 在授权复核失败路径会关两次（pg-pool 二次 end() 会抛的教训）。
+     * 关闭后一切访问都必须在此处被拦下——否则 mssql 池会以 ENOTOPEN 报英文错，
+     * 且跨库访问还会新建池（关不掉的连接泄漏）。
+     */
+    let closed = false;
+    const assertOpen = () => {
+        if (closed)
+            throw new Error('sqlserver 连接已关闭：请重新连接后重试');
+    };
+    const dbPools = new Map();
+    const poolOf = (db) => {
+        assertOpen();
+        if (!db)
+            return mainPool;
+        // SQL Server 库名默认不区分大小写：池键归一为小写，避免 MyDB / mydb 各建一个池（连接泄漏）。
+        const key = db.toLowerCase();
+        if (mainDb !== undefined && key === mainDb.toLowerCase())
+            return mainPool;
+        let box = dbPools.get(key);
+        if (!box) {
+            box = makePoolBox(Driver, { ...cfg, database: db });
+            dbPools.set(key, box);
+        }
+        return box;
+    };
+    // 事务激活期间 query/execute 必须走同一连接（mssql 的事务请求自带该连接）
+    let txObj = null;
+    const defaultSchema = () => {
+        const f = conn.fields;
+        return f && typeof f.schema === 'string' && f.schema ? f.schema : 'dbo';
+    };
+    /** 浏览目标：'db.schema'（跨库） | 'schema'（当前库） | 空（当前库默认 schema） */
+    const parseBrowseTarget = (ref, what) => {
+        if (!ref)
+            return { db: undefined, schema: defaultSchema() };
+        const i = ref.indexOf('.');
+        if (i < 0)
+            return { db: undefined, schema: assertIdent(ref, what) };
+        return { db: assertIdent(ref.slice(0, i), '数据库'), schema: assertIdent(ref.slice(i + 1), what) };
+    };
+    /** 取执行用的 request：事务中走事务连接（跨库请求不参与事务，与 pg-like 同语义） */
+    const requestFor = async (db) => {
+        assertOpen();
+        if (txObj && db === undefined)
+            return { req: txObj.request(), inTx: true };
+        const box = poolOf(db);
+        await box.ready();
+        return { req: box.pool.request(), inTx: false };
+    };
+    const tx = {
+        begin: () => wrap('sqlserver 事务开启', async () => {
+            if (txObj)
+                throw new Error('事务已开启，请勿重复 begin');
+            await mainPool.ready();
+            const t = new Driver.Transaction(mainPool.pool);
+            await t.begin();
+            txObj = t;
+        }),
+        commit: () => wrap('sqlserver 事务提交', async () => {
+            const t = txObj;
+            if (!t)
+                throw new Error('没有进行中的事务');
+            txObj = null;
+            await t.commit();
+        }),
+        rollback: () => wrap('sqlserver 事务回滚', async () => {
+            const t = txObj;
+            if (!t)
+                throw new Error('没有进行中的事务');
+            txObj = null;
+            await t.rollback();
+        }),
+    };
+    return {
+        kind: 'sqlserver',
+        connId: conn.meta.id,
+        tx,
+        testConnect: () => wrap('sqlserver 连接测试', async () => {
+            assertOpen();
+            await mainPool.ready();
+            const res = await mainPool.pool.request().query(TEST_CONNECT_SQL);
+            const row = rowsOf(res)[0];
+            const version = typeof row?.['version'] === 'string' ? row['version'] : '';
+            if (version === '')
+                return { ok: true, serverInfo: 'SQL Server（版本信息不可读）' };
+            return { ok: true, serverInfo: serverInfo(version, row?.['major'], row?.['engine']) };
+        }),
+        query: (sql, params, database) => wrap('sqlserver 查询失败', async () => {
+            const scan = scanSql(sql);
+            if (readOnly)
+                assertReadOnlyQuery(sql, scan);
+            const binds = params ?? [];
+            assertPlaceholderCount(scan, binds);
+            const db = database ? assertIdent(database, '数据库') : undefined;
+            const { req } = await requestFor(db);
+            const text = rewritePlaceholders(req, sql, scan, binds);
+            const res = await req.query(text);
+            return toQueryResult(res);
+        }),
+        execute: (statement, params, database) => wrap('sqlserver 执行失败', async () => {
+            // ro 连接由服务层拦截（本适配器不重复拦 execute：控制台事务通道也会用 execute 发读语句）
+            const scan = scanSql(statement);
+            const binds = params ?? [];
+            assertPlaceholderCount(scan, binds);
+            const db = database ? assertIdent(database, '数据库') : undefined;
+            const { req } = await requestFor(db);
+            const text = rewritePlaceholders(req, statement, scan, binds);
+            const res = await req.query(text);
+            const arr = res.rowsAffected ?? [];
+            let sum = 0;
+            let known = false;
+            for (const n of arr) {
+                if (typeof n === 'number' && Number.isFinite(n)) {
+                    sum += n;
+                    known = true;
+                }
+            }
+            return {
+                affectedRows: known ? sum : undefined,
+                message: known ? `执行成功，受影响 ${sum} 行` : '执行成功',
+            };
+        }),
+        listDatabases: () => wrap('sqlserver 列出数据库', async () => {
+            const box = poolOf(undefined); // 走主池并经 assertOpen（关闭后抛中文错误而非驱动英文错）
+            await box.ready();
+            const res = await box.pool.request().query(LIST_DATABASES_SQL);
+            return rowsOf(res).map((r) => String(r['name']));
+        }),
+        listSchemas: (database) => wrap('sqlserver 列出模式', async () => {
+            const box = poolOf(database ? assertIdent(database, '数据库') : undefined);
+            await box.ready();
+            const res = await box.pool.request().query(LIST_SCHEMAS_SQL);
+            return rowsOf(res).map((r) => String(r['name']));
+        }),
+        listTables: (database) => wrap('sqlserver 列出表', async () => {
+            const { db, schema } = parseBrowseTarget(database, 'schema');
+            const box = poolOf(db);
+            await box.ready();
+            const req = box.pool.request();
+            req.input('p1', schema);
+            const res = await req.query(LIST_TABLES_SQL);
+            return rowsOf(res).map((r) => {
+                const raw = String(r['obj_type']);
+                return {
+                    name: String(r['table_name']),
+                    type: raw === 'U' ? 'TABLE' : raw === 'V' ? 'VIEW' : raw,
+                    database: db ? `${db}.${schema}` : schema,
+                };
+            });
+        }),
+        describeTable: (table, database) => wrap('sqlserver 查看表结构', async () => {
+            const { db, schema } = parseBrowseTarget(database, 'schema');
+            const tbl = assertIdent(table, '表名');
+            const box = poolOf(db);
+            await box.ready();
+            const ref = `[${schema.replaceAll(']', ']]')}].[${tbl.replaceAll(']', ']]')}]`;
+            const colReq = box.pool.request();
+            colReq.input('p1', ref);
+            const cols = await colReq.query(DESCRIBE_COLUMNS_SQL);
+            const columnRows = rowsOf(cols);
+            if (columnRows.length === 0)
+                throw new Error(`表不存在: ${schema}.${tbl}`);
+            const pkReq = box.pool.request();
+            pkReq.input('p1', ref);
+            const pkRes = await pkReq.query(DESCRIBE_PK_SQL);
+            const pkIds = new Set(rowsOf(pkRes).map((r) => Number(r['column_id'])));
+            return columnRows.map((r) => {
+                const typeName = String(r['type_name']);
+                const comment = r['comment'];
+                const dflt = r['default_def'];
+                const id = Number(r['column_id']);
+                return {
+                    name: String(r['column_name']),
+                    dataType: formatDataType(typeName, Number(r['max_length'] ?? 0), Number(r['precision'] ?? 0), Number(r['scale'] ?? 0)),
+                    nullable: r['is_nullable'] === true || r['is_nullable'] === 1,
+                    key: pkIds.has(id) ? 'PRI' : undefined,
+                    default: dflt == null ? null : String(dflt),
+                    comment: comment == null || comment === '' ? undefined : String(comment),
+                };
+            });
+        }),
+        previewRows: (table, limit, database, offset) => wrap('sqlserver 预览行', async () => {
+            const { db, schema } = parseBrowseTarget(database, 'schema');
+            const tbl = assertIdent(table, '表名');
+            const lim = clampLimit(limit);
+            const off = clampOffset(offset);
+            const box = poolOf(db);
+            const major = await box.major();
+            const q = (name) => `[${name.replaceAll(']', ']]')}]`;
+            const target = `${q(schema)}.${q(tbl)}`;
+            if (major >= 11) {
+                // T-SQL 的 OFFSET/FETCH 强制要求 ORDER BY；(SELECT NULL) 是常量排序，等价于不指定顺序。
+                // 绑定：@p1 = 偏移，@p2 = 行数（FETCH NEXT @p2）。
+                const req = box.pool.request();
+                req.input('p1', off);
+                req.input('p2', lim);
+                const res = await req.query(`SELECT * FROM ${target} ORDER BY (SELECT NULL) OFFSET @p1 ROWS FETCH NEXT @p2 ROWS ONLY`);
+                return toQueryResult(res);
+            }
+            // 2008/2008 R2：无 OFFSET/FETCH，用 ROW_NUMBER 子查询降级；内部序号列在投影后剔除。
+            // 绑定：@p1 = 偏移，@p2 = 上界（off + lim，不是 lim！否则 offset>0 时第 2 页起恒为空）。
+            const req = box.pool.request();
+            req.input('p1', off);
+            req.input('p2', off + lim);
+            const res = await req.query(`SELECT t.* FROM (SELECT *, ROW_NUMBER() OVER (ORDER BY (SELECT NULL)) AS [__dsh_rn] FROM ${target}) AS t WHERE t.[__dsh_rn] > @p1 AND t.[__dsh_rn] <= @p2`);
+            return toQueryResult(res, ['__dsh_rn']);
+        }),
+        close: () => wrap('sqlserver 关闭连接', async () => {
+            if (closed)
+                return;
+            closed = true;
+            await Promise.all([mainPool.pool.close(), ...[...dbPools.values()].map((b) => b.pool.close())]);
+        }),
+    };
+}
+/** 传输层等内部调用用的工厂（注意：会丢弃 opts.mode，服务层注册表不得使用） */
+export const factory = (conn) => createSqlserverAdapter(conn);
+/**
+ * 数据传输端复用的独立原始池（绕过展示化转换，保真搬运）。
+ * 库名与主连接一致（跨库由调用方在 conn 上覆盖 database）。
+ */
+export async function openSqlserverRaw(conn, driver) {
+    const Driver = driver ?? vendor();
+    const cfg = poolConfig(conn);
+    const box = makePoolBox(Driver, cfg);
+    const database = typeof cfg.database === 'string' ? cfg.database : '';
+    return { pool: box.pool, ready: box.ready, database, driver: Driver };
+}