jsql-neo 6.0.2 → 6.0.4

package/lib/sql.js

@@ -11,6 +11,10 @@ const DANGEROUS_SQL = [
   { re: /^SYSEXEC$|^SYS_EXEC$/, name: 'sys_exec' },
 ];
 
+// SQL 文本体积上限（默认 64 MiB）：防止超大、无分号的输入造成无界内存消耗
+// （CWE-770）。可在 executeSQL 通过 opts.maxSqlLength 放宽/关闭（传 Infinity）。
+const DEFAULT_MAX_SQL_LENGTH = 64 * 1024 * 1024;
+
 function findDangerousSQL(tokens) {
   for (let i = 0; i < tokens.length; i++) {
     const t = tokens[i];
@@ -79,6 +83,13 @@ function tokenize(sql) {
       while (i < n && sql[i] !== '\n') i++;
       continue;
     }
+    // PG 的 JSON 路径操作符 #> / #>>（必须在 '#' 行注释之前识别）
+    if (c === '#' && sql[i + 1] === '>') {
+      const op = sql[i + 2] === '>' ? '#>>' : '#>';
+      tokens.push(new SQLToken('op', op, i));
+      i += op.length;
+      continue;
+    }
     if (c === '#' || (c === '/' && sql[i + 1] === '*')) {
       if (c === '#') { while (i < n && sql[i] !== '\n') i++; continue; }
       i += 2;
@@ -95,7 +106,10 @@ function tokenize(sql) {
         if (sql[j] === '\\' && j + 1 < n) {
           const esc = sql[j + 1];
           const map = { n: '\n', t: '\t', r: '\r', '0': '\0', "'": "'", '"': '"', '\\': '\\', b: '\b', Z: '\x1a', a: '\a' };
-          str += map[esc] !== undefined ? map[esc] : esc;
+          // MySQL 语义：\% 与 \_ 保留反斜杠（供 LIKE 匹配字面量通配符），其余未知转义忽略反斜杠
+          if (map[esc] !== undefined) str += map[esc];
+          else if (esc === '%' || esc === '_') str += '\\' + esc;
+          else str += esc;
           j += 2;
         } else if (sql[j] === quote) {
           break;
@@ -104,6 +118,7 @@ function tokenize(sql) {
           j++;
         }
       }
+      if (j >= n) throw new Error(`Unterminated ${quote === '"' ? 'double' : 'single'}-quoted string at position ${i}`);
       tokens.push(new SQLToken('string', str, i));
       i = j + 1;
       continue;
@@ -145,11 +160,19 @@ function tokenize(sql) {
     if (c === '`') {
       let j = i + 1;
       while (j < n && sql[j] !== '`') j++;
+      if (j >= n) throw new Error(`Unterminated backtick-quoted identifier at position ${i}`);
       tokens.push(new SQLToken('ident', sql.slice(i + 1, j), i));
       i = j + 1;
       continue;
     }
 
+    // PG 的 JSON 包含操作符 @>
+    if (c === '@' && sql[i + 1] === '>') {
+      tokens.push(new SQLToken('op', '@>', i));
+      i += 2;
+      continue;
+    }
+
     if (c === '@') {
       let j = i;
       while (j < n && sql[j] === '@') j++;
@@ -167,6 +190,12 @@ function tokenize(sql) {
     }
 
     // 参数占位符：? （顺序）、?N （编号）、?? （标识符占位）
+    // 注意：?| / ?& 是 PG 的 JSON 键存在操作符，必须优先识别
+    if (c === '?' && (sql[i + 1] === '|' || sql[i + 1] === '&')) {
+      tokens.push(new SQLToken('op', '?' + sql[i + 1], i));
+      i += 2;
+      continue;
+    }
     if (c === '?') {
       if (sql[i + 1] === '?') { tokens.push(new SQLToken('param', '??', i)); i += 2; continue; }
       let j = i + 1;
@@ -177,9 +206,22 @@ function tokenize(sql) {
       continue;
     }
 
+    const three = sql.slice(i, i + 3);
+    if (sql.slice(i, i + 2) === '<@') {
+      tokens.push(new SQLToken('op', '<@', i));
+      i += 2;
+      continue;
+    }
+    if (three === '->>' || three === '<=>' || three === '!~*') {
+      tokens.push(new SQLToken('op', three, i));
+      i += 3;
+      continue;
+    }
+
     const two = sql.slice(i, i + 2);
     if (two === '<=' || two === '>=' || two === '!=' || two === '<>' || two === '==' ||
-        two === '<<' || two === '>>') {
+        two === '<<' || two === '>>' || two === '->' || two === '::' ||
+        two === '&&' || two === '||' || two === '~*' || two === '!~') {
       tokens.push(new SQLToken('op', two, i));
       i += 2;
       continue;
@@ -523,19 +565,27 @@ class Parser {
   parseColumnDef() {
     const def = {};
     const typeTok = this.next();
-    if (typeTok.type !== 'keyword') throw new Error(`Expected column type, got '${typeTok.value}'`);
-    const type = typeTok.value.toLowerCase();
+    const typeRaw = String(typeTok.value);
+    // 这些类型不在 KEYWORDS 里（避免影响同名标识符），按上下文识别
+    const IDENT_TYPES = /^(BIG)?SERIAL$|^JSONB$|^TIMESTAMPTZ$|^BYTEA$|^UUID$/i;
+    const isIdentType = IDENT_TYPES.test(typeRaw);
+    if (typeTok.type !== 'keyword' && !isIdentType) throw new Error(`Expected column type, got '${typeTok.value}'`);
+    const type = typeRaw.toLowerCase();
     const typeMap = {
       integer: 'integer', int: 'integer', bigint: 'integer', tinyint: 'integer', smallint: 'integer',
       string: 'string', text: 'string', varchar: 'string', char: 'string',
       float: 'number', double: 'number', real: 'number', numeric: 'number', decimal: 'number',
       boolean: 'boolean', bool: 'boolean',
-      date: 'date', datetime: 'datetime', timestamp: 'timestamp',
-      any: 'any', object: 'object', json: 'object', array: 'array'
+      date: 'date', datetime: 'datetime', timestamp: 'timestamp', timestamptz: 'timestamp',
+      any: 'any', object: 'object', json: 'object', jsonb: 'object', array: 'array',
+      bytea: 'string', uuid: 'string',
+      // PG 自增序列类型：等价于整型 + 自增 + NOT NULL
+      serial: 'integer', bigserial: 'integer'
     };
     const mapped = typeMap[type];
     if (!mapped) throw new Error(`Unsupported column type: ${typeTok.value}`);
     def.type = mapped;
+    if (/^(BIG)?SERIAL$/i.test(typeRaw)) { def.autoIncrement = true; def.required = true; }
 
     // 长度限制: TEXT(255) / VARCHAR(100) / INTEGER(11) ...
     if (this.peek().type === 'op' && this.peek().value === '(') {
@@ -598,6 +648,11 @@ class Parser {
               def.defaultExpr = true;
             } else {
               def.default = this.parseValue();
+              // 允许字面量后带 :: 类型转换：DEFAULT '{}'::jsonb
+              if (this.peek().type === 'op' && this.peek().value === '::') {
+                this.next();
+                if (this.peek().type === 'keyword' || this.peek().type === 'ident') this.next();
+              }
             }
             break;
           case 'COLLATE':
@@ -772,7 +827,7 @@ class Parser {
           for (;;) {
             const col = this.parseColumnRef();
             this.expect('op', '=');
-            const val = this.parseValue();
+            const val = this.parseConflictValue();
             sets.push([col, val]);
             if (this.peek().value === ',') { this.next(); continue; }
             break;
@@ -852,6 +907,21 @@ class Parser {
     throw new Error(`Expected value, got '${t.value}'`);
   }
 
+  /**
+   * ON CONFLICT DO UPDATE 赋值右侧：
+   *   EXCLUDED.col —— PG：引用"本次本应插入的值"
+   *   VALUES(col)  —— MySQL 同义（在 parseValue 中处理）
+   *   其他字面量
+   */
+  parseConflictValue() {
+    if (this.isWord('EXCLUDED') && this.peek(1).type === 'op' && this.peek(1).value === '.') {
+      this.next(); this.next();
+      const col = this.parseColumnRef();
+      return { _excludedOf: col };
+    }
+    return this.parseValue();
+  }
+
   /**
    * WITH [RECURSIVE] name [(col, ...)] AS (SELECT ...), ... <statement>
    * CTE 在语法层解析为 { type:'with', ctes:[{name, columns, select}], statement }。
@@ -1628,18 +1698,33 @@ class Parser {
   }
 
   parseOr() {
+    let left = this.parseXor();
+    for (;;) {
+      const isOr = this.isKeyword('OR') || (this.peek().type === 'op' && this.peek().value === '||');
+      if (!isOr) break;
+      this.next();
+      const right = this.parseXor();
+      left = { type: 'or', left, right };
+    }
+    return left;
+  }
+
+  // 逻辑异或 XOR（MySQL 优先级：OR < XOR < AND）
+  parseXor() {
     let left = this.parseAnd();
-    while (this.isKeyword('OR')) {
+    while (this.isWord('XOR')) {
       this.next();
       const right = this.parseAnd();
-      left = { type: 'or', left, right };
+      left = { type: 'xor', left, right };
     }
     return left;
   }
 
   parseAnd() {
     let left = this.parseNot();
-    while (this.isKeyword('AND')) {
+    for (;;) {
+      const isAnd = this.isKeyword('AND') || (this.peek().type === 'op' && this.peek().value === '&&');
+      if (!isAnd) break;
       this.next();
       const right = this.parseNot();
       left = { type: 'and', left, right };
@@ -1981,15 +2066,65 @@ class Parser {
   }
 
   parseTerm() {
-    let node = this.parseOperand();
+    let node = this.parsePostfix(this.parseOperand());
     for (;;) {
       const t = this.peek();
       if (t.type === 'op' && (t.value === '*' || t.value === '/' || t.value === '%')) {
         this.next();
-        const right = this.parseOperand();
+        const right = this.parsePostfix(this.parseOperand());
         node = { type: 'arith', op: t.value, left: node, right };
         continue;
       }
+      // MySQL 整数除法：7 DIV 2 → 3
+      if (this.isWord('DIV')) {
+        this.next();
+        const right = this.parsePostfix(this.parseOperand());
+        node = { type: 'arith', op: 'DIV', left: node, right };
+        continue;
+      }
+      break;
+    }
+    return node;
+  }
+
+  /**
+   * 后缀运算符（绑定最紧）：PG 风格 `::` 类型转换、`->` / `->>` JSON 取值。
+   * 例：'5'::INT、meta->>'name'、meta->'addr'->>'city'。
+   */
+  parsePostfix(node) {
+    for (;;) {
+      const t = this.peek();
+      if (t.type === 'op' && t.value === '::') {
+        this.next();
+        const typeTok = this.next();
+        let dataType = String(typeTok.value).toUpperCase();
+        if (this.peek().type === 'op' && this.peek().value === '(') {
+          this.next();
+          let depth = 1, spec = '';
+          while (depth > 0 && this.peek().type !== 'eof') {
+            const tk = this.next();
+            if (tk.type === 'op' && tk.value === '(') depth++;
+            else if (tk.type === 'op' && tk.value === ')') { depth--; if (depth === 0) break; }
+            spec += tk.value;
+          }
+          dataType += '(' + spec + ')';
+        }
+        node = { type: 'cast', expr: node, dataType };
+        continue;
+      }
+      if (t.type === 'op' && (t.value === '->' || t.value === '->>')) {
+        this.next();
+        const key = this.parseValue();
+        node = { type: 'jsonAccess', operand: node, key, asText: t.value === '->>' };
+        continue;
+      }
+      // PG 路径取值：meta#>'{a,b}' / meta#>>'{a,b}'
+      if (t.type === 'op' && (t.value === '#>' || t.value === '#>>')) {
+        this.next();
+        const key = this.parseValue();
+        node = { type: 'jsonAccess', operand: node, key, asText: t.value === '#>>', isPath: true };
+        continue;
+      }
       break;
     }
     return node;
@@ -2085,7 +2220,31 @@ class Parser {
       const isILike = !(t2.type === 'keyword' && t2.value === 'LIKE');
       this.next();
       const pattern = this.parseValue();
-      return { type: 'like', operand: left, pattern, not, ci: isILike };
+      // 可选 ESCAPE 子句：LIKE '...' ESCAPE '!'
+      let escape = null;
+      if (this.isWord('ESCAPE')) { this.next(); escape = this.parseValue(); }
+      return { type: 'like', operand: left, pattern, not, ci: isILike, escape };
+    }
+
+    // PG 正则操作符（双目位置）：~（大小写敏感）/ ~*（不敏感）/ !~ / !~*
+    if (t2.type === 'op' && (t2.value === '~' || t2.value === '~*' || t2.value === '!~' || t2.value === '!~*')) {
+      this.next();
+      const pattern = this.parseValue();
+      return {
+        type: 'regexp', operand: left, pattern,
+        not: t2.value.startsWith('!') || not,
+        ci: t2.value.endsWith('*'),
+      };
+    }
+
+    // PG JSON 键存在：? / ?| / ?&
+    // 裸 `?` 在此处处于"运算符位置"，与值位置上的 `?` 参数占位符不冲突。
+    if ((t2.type === 'op' && (t2.value === '?|' || t2.value === '?&')) ||
+        (t2.type === 'param' && t2.value === null)) {
+      const mode = t2.type === 'param' ? '?' : t2.value;
+      this.next();
+      const keys = this.parseValue();
+      return { type: 'jsonKeyExists', operand: left, keys, mode, not };
     }
 
     // MySQL 中 RLIKE 是 REGEXP 的同义词
@@ -2095,7 +2254,14 @@ class Parser {
       return { type: 'regexp', operand: left, pattern, not };
     }
 
-    if (t2.type === 'op' && ['=', '!=', '<>', '<', '<=', '>', '>='].includes(t2.value)) {
+    // PG JSON 包含操作符
+    if (t2.type === 'op' && (t2.value === '@>' || t2.value === '<@')) {
+      this.next();
+      const right = this.parseBitwise();
+      return { type: 'jsonContains', op: t2.value, left, right, not };
+    }
+
+    if (t2.type === 'op' && ['=', '!=', '<>', '<', '<=', '>', '>=', '<=>'].includes(t2.value)) {
       this.next();
       // = ANY (SELECT ...) / > ALL (SELECT ...)
       const anyAll = this.isWord('ANY') || this.isWord('ALL') || this.isWord('SOME');
@@ -2209,6 +2375,8 @@ function resolveOperand(operand, row, ctx) {
         case '*': return l * r;
         case '/': return r === 0 ? null : l / r;
         case '%': return r === 0 ? null : l % r;
+        // MySQL 整数除法 DIV（结果向零取整）
+        case 'DIV': return r === 0 ? null : Math.trunc(Number(l) / Number(r));
         // 位运算：先按整数归一，与 MySQL 的整数位运算语义一致
         case '&': return (Number(l) | 0) & (Number(r) | 0);
         case '|': return (Number(l) | 0) | (Number(r) | 0);
@@ -2229,6 +2397,7 @@ function resolveOperand(operand, row, ctx) {
     case 'compare':
     case 'and':
     case 'or':
+    case 'xor':
     case 'not':
     case 'in':
     case 'isNull':
@@ -2253,6 +2422,44 @@ function resolveOperand(operand, row, ctx) {
       const v = resolveOperand(operand.expr, row, ctx);
       return applyCast(v, operand.dataType);
     }
+    case 'jsonAccess': {
+      let base = resolveOperand(operand.operand, row, ctx);
+      if (base === null || base === undefined) return null;
+      // JSON 列可能以字符串形式存储，先解析
+      if (typeof base === 'string') {
+        try { base = JSON.parse(base); } catch (e) { return null; }
+      }
+      const keys = operand.isPath ? parsePgPath(operand.key) : [operand.key];
+      let v = base;
+      for (const key of keys) {
+        if (v === null || v === undefined) return null;
+        if (Array.isArray(v)) {
+          const idx = Number(key);
+          v = Number.isInteger(idx) ? (idx < 0 ? v[v.length + idx] : v[idx]) : undefined;
+        } else if (typeof v === 'object') {
+          v = v[key];
+        } else {
+          return null;
+        }
+      }
+      if (v === undefined) return null;
+      if (operand.asText) {
+        if (v === null) return null;
+        return typeof v === 'object' ? JSON.stringify(v) : String(v);
+      }
+      return v;
+    }
+    case 'jsonContains': {
+      const l = resolveOperand(operand.left, row, ctx);
+      const r = resolveOperand(operand.right, row, ctx);
+      const res = jsonContains(l, r, operand.op === '<@');
+      return operand.not ? !res : res;
+    }
+    case 'jsonKeyExists': {
+      const base = resolveOperand(operand.operand, row, ctx);
+      const res = jsonKeyExists(base, operand.keys, operand.mode);
+      return operand.not ? !res : res;
+    }
     case 'quantified': {
       // = ANY / > ALL (SELECT ...) —— 需先由执行层物化成 operand._list
       const v = resolveOperand(operand.operand, row, ctx);
@@ -2471,13 +2678,76 @@ function seedRand(seed) {
 }
 
 // ci 默认 true：保持 LIKE 既有的大小写不敏感行为不变；ILIKE 同为不敏感。
-function likeMatch(value, pattern, ci = true) {
+// escape：可选转义符（ESCAPE 子句），默认反斜杠；转义符后跟 % _ 或转义符本身按字面量匹配。
+function likeMatch(value, pattern, ci = true, escape = '\\') {
   if (typeof value !== 'string') return false;
-  const regex = pattern
-    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-    .replace(/%/g, '.*')
-    .replace(/_/g, '.');
-  return new RegExp('^' + regex + '$', ci ? 'i' : '').test(value);
+  const p = String(pattern);
+  const e = (escape === null || escape === undefined || escape === '') ? '\\' : String(escape);
+  const reEsc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  let out = '';
+  for (let i = 0; i < p.length; i++) {
+    const ch = p[i];
+    if (ch === e && i + 1 < p.length && (p[i + 1] === '%' || p[i + 1] === '_' || p[i + 1] === e)) {
+      out += reEsc(p[i + 1]);
+      i++;
+      continue;
+    }
+    if (ch === '%') out += '.*';
+    else if (ch === '_') out += '.';
+    else out += reEsc(ch);
+  }
+  return new RegExp('^' + out + '$', ci ? 'i' : '').test(value);
+}
+
+/** 解析 PG 的路径字面量：'{a,b}' 或数组 → ['a','b'] */
+function parsePgPath(key) {
+  if (Array.isArray(key)) return key.map(String);
+  if (typeof key === 'string') {
+    const s = key.trim();
+    if (s.startsWith('{') && s.endsWith('}')) {
+      return s.slice(1, -1).split(',').map(x => x.trim().replace(/^"(.*)"$/, '$1')).filter(x => x !== '');
+    }
+    return [s];
+  }
+  return [String(key)];
+}
+
+/** 把可能是 JSON 字符串的值归一为 JS 值 */
+function toJsonValue(v) {
+  if (typeof v === 'string') { try { return JSON.parse(v); } catch (e) { return v; } }
+  return v;
+}
+
+/** JSON 包含语义（PG 的 @> / <@）。swap=true 时判断 target 是否包含 container。 */
+function jsonContains(a, b, swap) {
+  const container = toJsonValue(swap ? b : a);
+  const target = toJsonValue(swap ? a : b);
+  return jsonContainsValue(container, target);
+}
+
+function jsonContainsValue(container, target) {
+  if (target === null || target === undefined) return true;
+  if (Array.isArray(target)) {
+    if (!Array.isArray(container)) return false;
+    return target.every(t => container.some(c => jsonContainsValue(c, t)));
+  }
+  if (typeof target === 'object') {
+    if (container === null || typeof container !== 'object' || Array.isArray(container)) return false;
+    return Object.keys(target).every(k => Object.prototype.hasOwnProperty.call(container, k) && jsonContainsValue(container[k], target[k]));
+  }
+  if (Array.isArray(container)) return container.some(c => c === target || String(c) === String(target));
+  if (container !== null && typeof container === 'object') return false;
+  return container === target || String(container) === String(target);
+}
+
+/** JSON 键存在（PG 的 ? / ?| / ?&）。keys 为单个键名或 '{a,b}' 形式的键列表。 */
+function jsonKeyExists(base, keys, mode) {
+  const v = toJsonValue(base);
+  if (v === null || typeof v !== 'object' || Array.isArray(v)) return false;
+  const has = (k) => Object.prototype.hasOwnProperty.call(v, k);
+  if (mode === '?|') return parsePgPath(keys).some(has);
+  if (mode === '?&') return parsePgPath(keys).every(has);
+  return has(String(keys));
 }
 
 function extractEqualPushdown(expr, schema) {
@@ -2529,10 +2799,18 @@ function evaluateExpr(expr, row, ctx) {
   switch (expr.type) {
     case 'and': return evaluateExpr(expr.left, row, ctx) && evaluateExpr(expr.right, row, ctx);
     case 'or': return evaluateExpr(expr.left, row, ctx) || evaluateExpr(expr.right, row, ctx);
+    case 'xor': return Boolean(evaluateExpr(expr.left, row, ctx)) !== Boolean(evaluateExpr(expr.right, row, ctx));
     case 'not': return !evaluateExpr(expr.expr, row, ctx);
     case 'compare': {
       const l = resolveOperand(expr.left, row, ctx);
       const r = resolveOperand(expr.right, row, ctx);
+      // MySQL NULL 安全相等：NULL <=> NULL 为真；NULL <=> 值 为假
+      if (expr.op === '<=>') {
+        const ln = l === null || l === undefined;
+        const rn = r === null || r === undefined;
+        if (ln || rn) return ln && rn;
+        return l === r || String(l) === String(r);
+      }
       // SQL 标准：任何与 NULL 的比较结果为 UNKNOWN（在 WHERE/ON/HAVING 中视为 false）
       if (l === null || r === null) return false;
       // 布尔与数值互通（MySQL: 1 = TRUE、0 = FALSE）
@@ -2555,18 +2833,23 @@ function evaluateExpr(expr, row, ctx) {
     }
     case 'like': {
       const v = resolveOperand(expr.operand, row, ctx);
-      const r = likeMatch(v, expr.pattern, !!expr.ci);
+      const r = likeMatch(v, expr.pattern, !!expr.ci, expr.escape);
       return expr.not ? !r : r;
     }
     case 'quantified':
       return !!resolveOperand(expr, row, ctx);
+    case 'jsonContains':
+      return !!resolveOperand(expr, row, ctx);
     case 'regexp': {
       const v = resolveOperand(expr.operand, row, ctx);
       if (v === null || v === undefined) return false;
-      const re = new RegExp(String(expr.pattern), 'i');
+      // REGEXP / RLIKE 历史上就是大小写不敏感的；`~` 敏感、`~*` 不敏感
+      const re = new RegExp(String(expr.pattern), expr.ci === false ? '' : 'i');
       const r = re.test(String(v));
       return expr.not ? !r : r;
     }
+    case 'jsonKeyExists':
+      return !!resolveOperand(expr, row, ctx);
     case 'isTruth': {
       const v = resolveOperand(expr.operand, row, ctx);
       const isTrue = v === true || v === 1 || v === '1' || v === 'true' || v === 'TRUE' || v === 't' || (typeof v === 'number' && v !== 0);
@@ -2852,13 +3135,47 @@ class SQLExecutor {
           dataRows = dataRows.map(stripDefault);
         }
         const pkCols = schema ? Object.keys(schema).filter(k => schema[k].primaryKey) : [];
+        const uniqueCols = schema ? Object.keys(schema).filter(k => schema[k].unique && !schema[k].primaryKey) : [];
         let toInsert = dataRows;
         let updated = 0;
         let skipped = 0;
+        // 非主键 UNIQUE 约束：默认动作（无 ON CONFLICT / IGNORE / REPLACE）下违反即 ER_DUP_ENTRY。
+        // 主键冲突由下面的冲突逻辑处理；这里补唯一列（含批内重复）。
+        if (uniqueCols.length > 0 && this._conflictAction(statement) === 'throw') {
+          const existing = (await this.engine.find(statement.name, {}, { limit: 1e9, offset: 0 }))
+            .map(r => normalizeRow(r, schema));
+          for (const col of uniqueCols) {
+            const used = new Set();
+            for (const r of existing) {
+              const v = r[col];
+              if (v !== undefined && v !== null) used.add(String(v));
+            }
+            for (const d of dataRows) {
+              const v = d[col];
+              if (v === undefined || v === null) continue;   // UNIQUE 允许多个 NULL
+              const s = String(v);
+              if (used.has(s)) throw new Error(`ER_DUP_ENTRY: Duplicate entry '${s}' for unique column '${col}'`);
+              used.add(s);
+            }
+          }
+        }
         if (pkCols.length > 0) {
           const keyOf = (row) => pkCols.map(c => (row[c] !== undefined && row[c] !== null ? String(row[c]) : '')).join('|');
           const hasExplicitPk = (row) => pkCols.some(c => row[c] !== undefined && row[c] !== null);
-          const explicit = dataRows.filter(hasExplicitPk);
+          // 冲突判定的额外列组：
+          //   ON CONFLICT (col) DO UPDATE → 指定列（PG）
+          //   ON DUPLICATE KEY UPDATE     → 各唯一列（MySQL：任一唯一键冲突都触发）
+          // 此前只认主键，导致这两者在唯一列冲突时会插入重复行而不是更新。
+          const ocTarget = (statement.onConflict && Array.isArray(statement.onConflict.target))
+            ? statement.onConflict.target.map(c => (c && c.name !== undefined ? c.name : c)).filter(Boolean)
+            : null;
+          const extraIdx = [];
+          if (ocTarget && ocTarget.length) extraIdx.push(ocTarget);
+          // 唯一列始终参与冲突判定（PG 的 ON CONFLICT 与 MySQL 的 ON DUPLICATE 都包含唯一键）
+          for (const c of uniqueCols) extraIdx.push([c]);
+          const hasAllOf = (cols) => (row) => cols.every(c => row[c] !== undefined && row[c] !== null);
+
+          const explicit = dataRows.filter((row) => hasExplicitPk(row) || extraIdx.some((cols) => hasAllOf(cols)(row)));
           if (explicit.length > 0) {
             const all = (await this.engine.find(statement.name, {}, { limit: 1e9, offset: 0 })).map(r => normalizeRow(r, schema));
             const pkMap = new Map();
@@ -2866,15 +3183,31 @@ class SQLExecutor {
               const keys = pkCols.map(c => row[c]).filter(v => v !== undefined && v !== null);
               if (keys.length === pkCols.length) pkMap.set(keyOf(row), keys);
             }
+            const pkValsOf = (row) => pkCols.map(c => row[c]).filter(v => v !== undefined && v !== null);
+            const extraMaps = extraIdx.map((cols) => {
+              const m = new Map();
+              const pick = hasAllOf(cols);
+              const key = (row) => cols.map(c => String(row[c])).join('|');
+              for (const row of all) {
+                if (!pick(row)) continue;
+                m.set(key(row), pkValsOf(row));
+              }
+              return { pick, key, m };
+            });
             const conflicts = [];
             const fresh = [];
             for (const d of dataRows) {
-              const key = keyOf(d);
-              if (hasExplicitPk(d) && pkMap.has(key)) {
-                conflicts.push({ d, existingId: pkMap.get(key) });
-              } else {
-                fresh.push(d);
+              let existingId = null;
+              if (hasExplicitPk(d) && pkMap.has(keyOf(d))) existingId = pkMap.get(keyOf(d));
+              if (!existingId) {
+                for (const { pick, key, m } of extraMaps) {
+                  if (!pick(d)) continue;
+                  const k = key(d);
+                  if (m.has(k)) { existingId = m.get(k); break; }
+                }
               }
+              if (existingId) conflicts.push({ d, existingId });
+              else fresh.push(d);
             }
             const conflictAction = this._conflictAction(statement);
             const conflictSets = this._conflictSets(statement);
@@ -2902,10 +3235,14 @@ class SQLExecutor {
                 const data = {};
                 if (conflictSets) {
                   for (const [col, val] of conflictSets) {
-                    // VALUES(col) 引用本次本应插入的值
-                    data[col] = (val && typeof val === 'object' && val._valuesOf !== undefined)
-                      ? (d[val._valuesOf] !== undefined ? d[val._valuesOf] : null)
-                      : val;
+                    // VALUES(col) 引用本次本应插入的值；EXCLUDED.col 为 PG 同义写法
+                    if (val && typeof val === 'object' && val._valuesOf !== undefined) {
+                      data[col] = d[val._valuesOf] !== undefined ? d[val._valuesOf] : null;
+                    } else if (val && typeof val === 'object' && val._excludedOf !== undefined) {
+                      data[col] = d[val._excludedOf] !== undefined ? d[val._excludedOf] : null;
+                    } else {
+                      data[col] = val;
+                    }
                   }
                 } else {
                   for (const k of Object.keys(d)) if (!pkCols.includes(k)) data[k] = d[k];
@@ -4493,53 +4830,88 @@ class SQLExecutor {
   }
 }
 
-function splitStatements(sql) {
-  const statements = [];
-  let current = '';
-  let inStr = null;   // "'" | '"' | '`'
-  let i = 0;
-  while (i < sql.length) {
+/** 跳过一个引号串（含转义/反引号成对），返回闭合引号之后的下标 */
+function skipQuoted(sql, i, q) {
+  const n = sql.length;
+  i++;   // 跳过起始引号
+  while (i < n) {
     const c = sql[i];
-    if (inStr) {
-      current += c;
-      if (inStr === '`') {
-        // 反引号标识符内部反斜杠不是转义符；两个连续反引号才表示一个字面反引号。
-        if (c === '`' && sql[i + 1] === '`') { current += sql[i + 1]; i += 2; continue; }
-        if (c === '`') inStr = null;
-        i++;
-        continue;
+    if (q === '`') {
+      // 反引号标识符内部反斜杠不是转义符；两个连续反引号表示一个字面反引号。
+      if (c === '`') {
+        if (sql[i + 1] === '`') { i += 2; continue; }
+        return i + 1;
       }
-      if (c === '\\' && i + 1 < sql.length) { current += sql[i + 1]; i += 2; continue; }
-      if (c === inStr) inStr = null;
       i++;
       continue;
     }
-    if (c === "'" || c === '"' || c === '`') { inStr = c; current += c; i++; continue; }
+    if (c === '\\') { i += 2; continue; }
+    if (c === q) return i + 1;
+    i++;
+  }
+  return n;   // 未闭合：到结尾
+}
+
+function splitStatements(sql, opts = {}) {
+  if (typeof sql !== 'string') {
+    throw new Error('splitStatements: sql must be a string');
+  }
+  const maxLength = opts.maxLength == null ? DEFAULT_MAX_SQL_LENGTH : opts.maxLength;
+  if (typeof maxLength === 'number' && Number.isFinite(maxLength) && sql.length > maxLength) {
+    throw new Error(
+      `SQL text too large: ${sql.length} chars exceeds limit of ${maxLength} ` +
+      `(raise opts.maxSqlLength to allow larger input)`
+    );
+  }
+  const statements = [];
+  // 用「区间切片」收集，而不是逐字符拼接：既避免 `current += c` 的 O(n²) 拷贝放大，
+  // 也避免为每个字符建一个小字符串对象（20MB 无分号输入下两者都会打爆默认堆）。
+  let parts = [];
+  const take = end => { parts.push(sql.slice(segStart, end)); };
+  const flush = () => {
+    if (parts.length === 0) return;
+    const stmt = parts.join('').trim();
+    parts = [];
+    if (stmt) statements.push(stmt);
+  };
+
+  let segStart = 0;
+  let i = 0;
+  const n = sql.length;
+  while (i < n) {
+    const c = sql[i];
+    if (c === "'" || c === '"' || c === '`') { i = skipQuoted(sql, i, c); continue; }
     if (c === '-' && sql[i + 1] === '-') {
-      while (i < sql.length && sql[i] !== '\n') i++;
+      // 行注释：丢弃注释文本本身（与原实现一致），保留其后的换行
+      take(i);
+      while (i < n && sql[i] !== '\n') i++;
+      segStart = i;
       continue;
     }
-    if (c === '#') {
-      while (i < sql.length && sql[i] !== '\n') i++;
+    if (c === '#' && sql[i + 1] !== '>') {
+      take(i);
+      while (i < n && sql[i] !== '\n') i++;
+      segStart = i;
       continue;
     }
     if (c === '/' && sql[i + 1] === '*') {
-      current += '/*';
+      // 块注释：原实现会保留 `/* */` 原文，这里通过切片一并保留
       i += 2;
-      while (i + 1 < sql.length && !(sql[i] === '*' && sql[i + 1] === '/')) { current += sql[i]; i++; }
-      if (i + 1 < sql.length) { current += '*/'; i += 2; }
+      while (i + 1 < n && !(sql[i] === '*' && sql[i + 1] === '/')) i++;
+      i = i + 1 < n ? i + 2 : n;
       continue;
     }
     if (c === ';') {
-      if (current.trim()) statements.push(current.trim());
-      current = '';
+      take(i);
+      flush();
       i++;
+      segStart = i;
       continue;
     }
-    current += c;
     i++;
   }
-  if (current.trim()) statements.push(current.trim());
+  take(n);
+  flush();
   return statements;
 }
 
@@ -4566,7 +4938,7 @@ function hasComments(sql) {
     if (c === "'" || c === '"') { inStr = c; i++; continue; }
     if (c === '`') { i++; while (i < sql.length && sql[i] !== '`') i++; i++; continue; }
     if (c === '-' && sql[i + 1] === '-') return true;
-    if (c === '#') return true;
+    if (c === '#' && sql[i + 1] !== '>') return true;   // '#>' / '#>>' 是 JSON 操作符，不是注释
     if (c === '/' && sql[i + 1] === '*') return true;
     i++;
   }
@@ -4615,16 +4987,34 @@ function applyParams(sql, values) {
   if (args && typeof args === 'object' && !Array.isArray(args)) {
     hasNamed = true;
   }
-  while (i < sql.length) {
+  const n = sql.length;
+  while (i < n) {
     const c = sql[i];
     if (inStr) {
       out += c;
-      if (c === '\\' && i + 1 < sql.length) { out += sql[i + 1]; i += 2; continue; }
+      if (c === '\\' && i + 1 < n) { out += sql[i + 1]; i += 2; continue; }
       if (c === inStr) inStr = null;
       i++;
       continue;
     }
     if (c === "'" || c === '"' || c === '`') { inStr = c; out += c; i++; continue; }
+    // 跳过注释：`--` 和 `#`（但 `#>` / `#>>` 是 JSON 操作符，不是注释）
+    if (c === '-' && sql[i + 1] === '-') {
+      // 行注释：整段跳过，保留换行（不在注释里的字符不进入 out）
+      while (i < n && sql[i] !== '\n') i++;
+      continue;
+    }
+    if (c === '#' && sql[i + 1] !== '>') {
+      while (i < n && sql[i] !== '\n') i++;
+      continue;
+    }
+    if (c === '/' && sql[i + 1] === '*') {
+      // 块注释：整段跳过
+      i += 2;
+      while (i + 1 < n && !(sql[i] === '*' && sql[i + 1] === '/')) i++;
+      if (i + 1 < n) i += 2; else i = n;
+      continue;
+    }
     if (c === '?' && sql[i + 1] === '?') {
       if (!hasNamed && idx >= args.length) throw new Error('Not enough parameters for SQL: expected ' + (count + 1));
       out += escapeId(hasNamed ? args['@@'] : args[idx++]);
@@ -4657,6 +5047,24 @@ function applyParams(sql, values) {
       i++;
       continue;
     }
+    // $N 编号占位符（PG 风格）：$1 / $2 ...
+    if (c === '$' && i + 1 < sql.length && sql[i + 1] >= '0' && sql[i + 1] <= '9') {
+      let num = '';
+      let j = i + 1;
+      while (j < sql.length && sql[j] >= '0' && sql[j] <= '9') { num += sql[j]; j++; }
+      const n = parseInt(num, 10);
+      if (hasNamed) {
+        if (!(n in args)) throw new Error(`No value for parameter $${n}`);
+        out += escapeValue(args[n]);
+      } else {
+        if (n - 1 >= args.length) throw new Error(`Not enough parameters for SQL: expected $${n}`);
+        out += escapeValue(args[n - 1]);
+        if (n > idx) idx = n;
+      }
+      count++;
+      i = j;
+      continue;
+    }
     if ((c === ':' || c === '@' || c === '$') && i + 1 < sql.length && /[A-Za-z_]/.test(sql[i + 1])) {
       // 命名占位符 :name @name $name
       let name = '';
@@ -4678,6 +5086,44 @@ function applyParams(sql, values) {
   return out;
 }
 
+// 把执行器结果补齐为 README 承诺的结果信封
+// （columnTypes / rowCount / message / command / durationMs / warnings）
+function buildResultEnvelope(stmt, r, durationMs) {
+  if (r === null || typeof r !== 'object' || Array.isArray(r)) return r;
+  const out = { ...r };
+  const t = stmt && stmt.type;
+  if (out.command === undefined) out.command = String(t || '').toUpperCase();
+  if (out.affectedRows === undefined) out.affectedRows = 0;
+  if (out.rowCount === undefined) {
+    out.rowCount = Array.isArray(out.rows) ? out.rows.length
+      : (typeof out.affectedRows === 'number' ? out.affectedRows : 0);
+  }
+  if (out.warnings === undefined) out.warnings = [];
+  if (out.durationMs === undefined) out.durationMs = durationMs;
+  if (out.message === undefined) {
+    out.message = t === 'select'
+      ? `${out.rowCount} row${out.rowCount === 1 ? '' : 's'} selected`
+      : `${out.affectedRows} row${out.affectedRows === 1 ? '' : 's'} affected`;
+  }
+  return out;
+}
+
+// SELECT 结果的列类型：单表查询按 schema 推断；表达式/多表查询该列为 null
+async function inferColumnTypes(engine, stmt, r) {
+  if (!r || !Array.isArray(r.columns)) return undefined;
+  let schema = null;
+  try {
+    const t = stmt && stmt.type === 'select' && stmt.from &&
+      Array.isArray(stmt.from.tables) && stmt.from.tables.length === 1
+      ? stmt.from.tables[0].table : null;
+    if (t && engine && typeof engine.getTableSchema === 'function') schema = await engine.getTableSchema(t);
+  } catch (e) { schema = null; }
+  return r.columns.map((name) => {
+    const def = schema && schema[name];
+    return def && def.type ? sqlTypeName(def.type).toUpperCase() : null;
+  });
+}
+
 async function executeSQL(engine, sql, paramsOrOpts, opts = {}) {
   // 参数守卫：engine 必须是引擎对象，sql 必须是字符串。误用时报清晰错误，
   // 而不是在后续像 `reading 'length'` 那样抛出令人费解的 TypeError。
@@ -4701,14 +5147,19 @@ async function executeSQL(engine, sql, paramsOrOpts, opts = {}) {
   if (Array.isArray(paramsOrOpts)) {
     sql = applyParams(sql, paramsOrOpts);
   } else if (paramsOrOpts && typeof paramsOrOpts === 'object') {
-    opts = paramsOrOpts;
+    // 第三参为对象时：含已知 opts 键 → 视为 opts；否则视为命名参数（{id: 1} → :id / $id）
+    const OPTS_KEYS = ['safety', 'session', 'params', 'functions', 'aggregates',
+      'allowComments', 'maxStatements', 'maxSqlLength', 'context', 'timeout', 'dialect'];
+    const looksLikeOpts = Object.keys(paramsOrOpts).some(k => OPTS_KEYS.includes(k));
+    if (looksLikeOpts) opts = paramsOrOpts;
+    else sql = applyParams(sql, paramsOrOpts);
   }
   if (opts.safety !== false) {
     if (!opts.allowComments && hasComments(sql)) {
       throw new Error('SQL comments are disabled for security (--, #, /* */)');
     }
   }
-  let statements = splitStatements(sql);
+  let statements = splitStatements(sql, { maxLength: opts.maxSqlLength });
   if (opts.maxStatements != null && statements.length > opts.maxStatements) {
     throw new Error(`too many statements (${statements.length} > ${opts.maxStatements})`);
   }
@@ -4727,7 +5178,14 @@ async function executeSQL(engine, sql, paramsOrOpts, opts = {}) {
   const results = [];
   for (const stmtSql of statements) {
     const stmt = parseSQL(stmtSql);
-    results.push(await executor.execute(stmt));
+    const t0 = process.hrtime.bigint();
+    let r = await executor.execute(stmt);
+    const durationMs = Number(process.hrtime.bigint() - t0) / 1e6;
+    r = buildResultEnvelope(stmt, r, Math.round(durationMs * 1000) / 1000);
+    if (r && r.columns && r.columnTypes === undefined) {
+      r.columnTypes = await inferColumnTypes(engine, stmt, r);
+    }
+    results.push(r);
   }
   return results.length === 1 ? results[0] : results;
 }