jsql-neo 6.0.0 → 6.1.0

package/lib/sql.js

@@ -79,6 +79,11 @@ function tokenize(sql) {
       while (i < n && sql[i] !== '\n') i++;
       continue;
     }
+    // PG 的 JSON 路径操作符 #> / #>> 尚未实现。
+    // 若不在这里拦截，'#' 会被当成行注释吃掉，导致 SQL 后半段被静默丢弃。
+    if (c === '#' && sql[i + 1] === '>') {
+      throw new Error("JSON 路径操作符 '#>' / '#>>' 暂不支持，请改用 '->' / '->>'");
+    }
     if (c === '#' || (c === '/' && sql[i + 1] === '*')) {
       if (c === '#') { while (i < n && sql[i] !== '\n') i++; continue; }
       i += 2;
@@ -95,7 +100,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;
@@ -150,6 +158,12 @@ function tokenize(sql) {
       continue;
     }
 
+    // PG 的 JSON 包含操作符 @> 尚未实现。
+    // 若不拦截，'@' 会被 sysvar 分支静默吞掉、'>' 退化成普通大于号，产生错误结果。
+    if (c === '@' && sql[i + 1] === '>') {
+      throw new Error("JSON 包含操作符 '@>' 暂不支持");
+    }
+
     if (c === '@') {
       let j = i;
       while (j < n && sql[j] === '@') j++;
@@ -177,14 +191,29 @@ function tokenize(sql) {
       continue;
     }
 
+    const three = sql.slice(i, i + 3);
+    if (sql.slice(i, i + 2) === '<@') {
+      throw new Error("JSON 包含操作符 '<@' 暂不支持");
+    }
+    if (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 === '==') {
+    if (two === '<=' || two === '>=' || two === '!=' || two === '<>' || two === '==' ||
+        two === '<<' || two === '>>' || two === '->' || two === '::' ||
+        two === '&&' || two === '||') {
       tokens.push(new SQLToken('op', two, i));
       i += 2;
       continue;
     }
 
-    if ('=<>+-*/(),.;'.includes(c)) {
+    // 注意：% & | ^ ~ 这些运算符必须在词法层产出 token。
+    // 之前 parseTerm() 里写了 '%' 分支但字符集里没有 '%'，
+    // 导致 SELECT 10 % 3 直接报 "Unexpected character '%'"，那段是死代码。
+    if ('=<>+-*/(),.;%&|^~'.includes(c)) {
       tokens.push(new SQLToken('op', c, i));
       i++;
       continue;
@@ -197,11 +226,23 @@ function tokenize(sql) {
   return tokens;
 }
 
+// 聚合函数集合：这些必须走 aggregate 节点，否则会被当成逐行标量函数（返回 null 且不折叠行）
+const AGG_FUNCS = new Set(['SUM', 'AVG', 'MIN', 'MAX', 'COUNT',
+  'GROUP_CONCAT', 'STDDEV', 'STDDEV_POP', 'STDDEV_SAMP',
+  'VARIANCE', 'VAR_POP', 'VAR_SAMP', 'FIRST', 'LAST']);
+
+// 这些词会跟在表名/子查询之后，不能被误当成表别名。
+// 新增任何"跟在 FROM 之后"的子句时，都要往这里加词。
+const NOT_ALIAS_WORDS = ['JOIN', 'LEFT', 'RIGHT', 'FULL', 'WHERE', 'GROUP', 'ORDER', 'LIMIT',
+  'ON', 'HAVING', 'UNION', 'INNER', 'CROSS', 'OUTER', 'INTERSECT', 'EXCEPT',
+  'FETCH', 'RETURNING', 'WINDOW', 'OFFSET', 'FOR'];
+
 class Parser {
   constructor(tokens) {
     this.tokens = tokens;
     this.pos = 0;
     this.paramCount = 0;   // 顺序占位符 ? 的序号（从 0 开始）
+    this.subquerySeq = 0;  // FROM 子查询无别名时自动生成 __subN
   }
 
   peek(offset = 0) { return this.tokens[this.pos + offset]; }
@@ -271,11 +312,13 @@ class Parser {
         if (this.isKeyword('TABLE', 1)) return this.parseCreateTable();
         if (this.isKeyword('DATABASE', 1)) return this.parseCreateDatabase();
         if (this.isWord('VIEW', 1) || this.isWord('OR', 1)) return this.parseCreateView();
+        if (this.isKeyword('INDEX', 1) || this.isKeyword('UNIQUE', 1)) return this.parseCreateIndex();
         throw new Error('Unsupported CREATE statement');
       case 'DROP':
         if (this.isKeyword('TABLE', 1)) return this.parseDropTable();
         if (this.isKeyword('DATABASE', 1)) return this.parseDropDatabase();
         if (this.isWord('VIEW', 1)) return this.parseDropView();
+        if (this.isKeyword('INDEX', 1)) return this.parseDropIndex();
         throw new Error('Unsupported DROP statement');
       case 'INSERT': return this.parseInsert();
       case 'REPLACE': return this.parseReplace();
@@ -351,6 +394,45 @@ class Parser {
     return { type: 'createView', name, columns, select, orReplace };
   }
 
+  /**
+   * CREATE [UNIQUE] INDEX name ON table (col [, col]...)
+   * 归一成 { type:'createIndex', name, table, columns, unique }
+   */
+  parseCreateIndex() {
+    this.expectKeyword('CREATE');
+    let unique = false;
+    if (this.isKeyword('UNIQUE')) { this.next(); unique = true; }
+    if (!this.isKeyword('INDEX')) throw new Error(`Expected INDEX, got '${this.peek().value}'`);
+    this.next();
+    const name = this.parseTableName();
+    if (!this.isKeyword('ON')) throw new Error(`Expected ON in CREATE INDEX, got '${this.peek().value}'`);
+    this.next();
+    const table = this.parseTableName();
+    this.expect('op', '(');
+    const columns = [];
+    for (;;) {
+      columns.push(this.parseColumnRef());
+      if (this.peek().type === 'op' && this.peek().value === ',') { this.next(); continue; }
+      break;
+    }
+    this.expect('op', ')');
+    this.optionalTailSemicolon();
+    return { type: 'createIndex', name, table, columns, unique };
+  }
+
+  /** DROP INDEX name ON table */
+  parseDropIndex() {
+    this.expectKeyword('DROP');
+    this.expectKeyword('INDEX');
+    let ifExists = false;
+    if (this.isKeyword('IF')) { this.expectKeyword('IF'); this.expectKeyword('EXISTS'); ifExists = true; }
+    const name = this.parseTableName();
+    let table = null;
+    if (this.isKeyword('ON')) { this.next(); table = this.parseTableName(); }
+    this.optionalTailSemicolon();
+    return { type: 'dropIndex', name, table, ifExists };
+  }
+
   parseDropView() {
     this.expectKeyword('DROP');
     if (!this.isWord('VIEW')) throw new Error(`Expected VIEW, got '${this.peek().value}'`);
@@ -413,6 +495,9 @@ class Parser {
           hasPk = true;
         } else {
           this.expectKeyword('UNIQUE');
+          // UNIQUE [KEY|INDEX] [name] (cols...)
+          if (this.isKeyword('KEY') || this.isKeyword('INDEX')) this.next();
+          if (this.peek().type === 'ident') this.next();
           this.expect('op', '(');
           const uCols = [this.parseTableName()];
           while (this.peek().type === 'op' && this.peek().value === ',') {
@@ -426,7 +511,12 @@ class Parser {
         }
       } else if (t.type === 'keyword' && t.value === 'CONSTRAINT') {
         this.expectKeyword('CONSTRAINT');
-        this.next();
+        if (this.peek().type === 'ident') this.next();   // 约束名
+        this._parseTableConstraint(schema);
+      } else if (this.isWord('FOREIGN') || this.isWord('CHECK') ||
+                 t.type === 'keyword' && (t.value === 'KEY' || t.value === 'INDEX')) {
+        // 表级约束：FOREIGN KEY ... REFERENCES ... / CHECK (...) / KEY name (cols)
+        this._parseTableConstraint(schema);
       } else if (t.type === 'eof' || (t.type === 'op' && t.value === ')')) {
         break;
       } else {
@@ -458,19 +548,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 === '(') {
@@ -517,7 +615,29 @@ class Parser {
           case 'NULL':
             this.next(); break;
           case 'DEFAULT':
-            this.next(); def.default = this.parseValue(); break;
+            this.next();
+            // 默认值可以是字面量，也可以是函数/关键字形式（CURRENT_TIMESTAMP / NOW() 等）。
+            // 函数形式存成字符串 + defaultExpr 标记，与 JS 侧 `default: 'CURRENT_TIMESTAMP'` 约定一致。
+            if (this.peek().type === 'ident' ||
+                (this.peek().type === 'keyword' && !['NULL', 'TRUE', 'FALSE'].includes(this.peek().value))) {
+              const fnTok = this.next();
+              let name = String(fnTok.value);
+              if (this.peek().type === 'op' && this.peek().value === '(') {
+                this.next();
+                this.expect('op', ')');
+                name += '()';
+              }
+              def.default = name;
+              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':
             this.next(); if (this.peek().type !== 'op' && this.peek().type !== 'eof') this.next(); break;
           case 'CHARACTER':
@@ -553,6 +673,68 @@ class Parser {
     return stmt;
   }
 
+  /** 跳过一对括号（含嵌套），用于表级约束里的列清单 */
+  _skipParens() {
+    this.expect('op', '(');
+    let depth = 1;
+    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--;
+    }
+  }
+
+  /**
+   * 解析表级约束（FOREIGN KEY / CHECK / KEY / INDEX / PRIMARY KEY / UNIQUE）。
+   * 目前只做语法层面消费并在可能时补充列属性，不做外键实际校验。
+   */
+  _parseTableConstraint(schema) {
+    if (this.isWord('FOREIGN')) {
+      this.next();
+      if (!this.isKeyword('KEY')) throw new Error(`Expected KEY after FOREIGN, got '${this.peek().value}'`);
+      this.next();
+      if (this.peek().type === 'op' && this.peek().value === '(') this._skipParens();
+      if (this.isWord('REFERENCES')) {
+        this.next();
+        this.parseTableName();
+        if (this.peek().type === 'op' && this.peek().value === '(') this._skipParens();
+      }
+      // ON DELETE / ON UPDATE <action>
+      while (this.isKeyword('ON')) {
+        this.next();
+        this.next();                       // DELETE | UPDATE
+        const act = String(this.next().value).toUpperCase();
+        if (act === 'SET' || act === 'NO') this.next();   // SET NULL / NO ACTION
+      }
+      return;
+    }
+    if (this.isWord('CHECK')) {
+      this.next();
+      if (this.peek().type === 'op' && this.peek().value === '(') this._skipParens();
+      return;
+    }
+    if (this.isKeyword('PRIMARY')) {
+      this.expectKeyword('PRIMARY');
+      if (this.isKeyword('KEY')) this.next();
+      if (this.peek().type === 'op' && this.peek().value === '(') {
+        this.next();
+        const cols = [this.parseTableName()];
+        while (this.peek().type === 'op' && this.peek().value === ',') { this.next(); cols.push(this.parseTableName()); }
+        this.expect('op', ')');
+        for (const c of cols) if (schema[c]) schema[c].primaryKey = true;
+      }
+      return;
+    }
+    if (this.isKeyword('UNIQUE')) {
+      this.next();
+    }
+    if (this.isKeyword('KEY') || this.isKeyword('INDEX')) {
+      this.next();
+      if (this.peek().type === 'ident') this.next();     // 索引名
+      if (this.peek().type === 'op' && this.peek().value === '(') this._skipParens();
+    }
+  }
+
   parseInsertBody() {
     const name = this.parseTableName();
     let columns = null;
@@ -628,7 +810,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;
@@ -683,6 +865,13 @@ class Parser {
   parseValue() {
     const t = this.next();
     if (t.type === 'number' || t.type === 'string') return t.value;
+    // MySQL: ON DUPLICATE KEY UPDATE col = VALUES(col) —— 引用"本次本应插入的值"
+    if (t.type === 'keyword' && t.value === 'VALUES' && this.peek().type === 'op' && this.peek().value === '(') {
+      this.next();
+      const col = this.parseColumnRef();
+      this.expect('op', ')');
+      return { _valuesOf: col };
+    }
     if (t.type === 'keyword' && t.value === 'NULL') return null;
     if (t.type === 'keyword' && t.value === 'TRUE') return true;
     if (t.type === 'keyword' && t.value === 'FALSE') return false;
@@ -701,6 +890,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 }。
@@ -833,24 +1037,37 @@ class Parser {
       if (t.type === 'keyword' && t.value === 'COUNT') {
         this.next();
         this.expect('op', '(');
+        let aggDistinct = false;
+        if (this.isKeyword('DISTINCT')) { this.next(); aggDistinct = true; }
         let col = null;
         if (this.peek().type === 'op' && this.peek().value === '*') { this.next(); }
         else if (!(this.peek().type === 'op' && this.peek().value === ')')) col = this.parseScalar();
+        // COUNT(DISTINCT a, b) —— 多列去重（仅对 COUNT 有意义，其它聚合按元组处理）
+        if (aggDistinct && this.peek().type === 'op' && this.peek().value === ',') {
+          const cols = [col];
+          while (this.peek().type === 'op' && this.peek().value === ',') {
+            this.next();
+            cols.push(this.parseScalar());
+          }
+          col = { type: 'tuple', items: cols };
+        }
         this.expect('op', ')');
-        aggregate = { type: 'COUNT', column: col };
+        aggregate = { type: 'COUNT', column: col, distinct: aggDistinct };
         aggregate = this.parseOptionalOver(aggregate);
         aggregate.alias = this.parseOptionalAlias();
-        columns.push({ expr: col, aggregate: 'COUNT', column: col, alias: aggregate.alias, over: aggregate.over || null, window: !!aggregate.over });
+        columns.push({ expr: col, aggregate: 'COUNT', column: col, alias: aggregate.alias, over: aggregate.over || null, window: !!aggregate.over, distinct: aggDistinct });
       } else if (t.type === 'keyword' && ['SUM', 'AVG', 'MIN', 'MAX'].includes(t.value)) {
         this.next();
         const fn = t.value;
         this.expect('op', '(');
+        let aggDistinct2 = false;
+        if (this.isKeyword('DISTINCT')) { this.next(); aggDistinct2 = true; }
         const col = this.parseScalar();
         this.expect('op', ')');
-        aggregate = { type: fn, column: col };
+        aggregate = { type: fn, column: col, distinct: aggDistinct2 };
         aggregate = this.parseOptionalOver(aggregate);
         aggregate.alias = this.parseOptionalAlias();
-        columns.push({ expr: col, aggregate: fn, column: col, alias: aggregate.alias, over: aggregate.over || null, window: !!aggregate.over });
+        columns.push({ expr: col, aggregate: fn, column: col, alias: aggregate.alias, over: aggregate.over || null, window: !!aggregate.over, distinct: aggDistinct2 });
       } else if (t.type === 'op' && t.value === '*') {
         this.next();
         columns.push({ expr: '*' });
@@ -867,7 +1084,7 @@ class Parser {
         if (expr.type === 'star') {
           columns.push({ expr: '*' });
         } else if (expr.type === 'aggregate') {
-          columns.push({ expr: expr.column, aggregate: expr.fn, column: expr.column, alias, scalar: expr });
+          columns.push({ expr: expr.column, aggregate: expr.fn, column: expr.column, alias, scalar: expr, distinct: expr.distinct, separator: expr.separator, orderBy: expr.orderBy });
         } else if (expr.type === 'column') {
           columns.push({ expr: expr.name, scalar: expr, alias });
         } else {
@@ -886,6 +1103,7 @@ class Parser {
     let where = null;
     if (this.isKeyword('WHERE')) { this.next(); where = this.parseExpr(); }
     let groupBy = null;
+    let rollup = false;
     if (this.isKeyword('GROUP')) {
       this.expectKeyword('GROUP'); this.expectKeyword('BY');
       groupBy = [];
@@ -894,6 +1112,12 @@ class Parser {
         if (this.peek().type === 'op' && this.peek().value === ',') { this.next(); continue; }
         break;
       }
+      // WITH ROLLUP 必须紧跟 GROUP BY 列表，之后才是 HAVING / ORDER BY / LIMIT
+      // （标准顺序：GROUP BY <list> [WITH ROLLUP] [HAVING] [ORDER BY] [LIMIT]）
+      if (this.isKeyword('WITH') && this.isWord('ROLLUP', 1)) {
+        this.next(); this.next();
+        rollup = true;
+      }
     }
     let having = null;
     if (this.isKeyword('HAVING')) { this.next(); having = this.parseExpr(); }
@@ -961,13 +1185,6 @@ class Parser {
       else if (this.isKeyword('DISTINCT')) this.next();
       except = { all, select: this.parseSelect() };
     }
-    // GROUP BY ... WITH ROLLUP
-    let rollup = false;
-    if (groupBy && this.isKeyword('WITH')) {
-      this.next();
-      if (this.isWord('ROLLUP')) { this.next(); rollup = true; }
-      else throw new Error(`Expected ROLLUP after WITH, got '${this.peek().value}'`);
-    }
     // FETCH FIRST n ROWS ONLY（SQL 标准的 LIMIT 写法）
     if (this.isWord('FETCH')) {
       this.next();
@@ -1029,19 +1246,18 @@ class Parser {
       this.expect('op', ')');
       let alias = null;
       if (this.isKeyword('AS')) { this.next(); alias = this.parseAlias(); }
-      else if (this.peek().type === 'ident') { alias = this.next().value; }
-      if (!alias) throw new Error('Subquery in FROM requires an alias');
+      else if (this.peek().type === 'ident' && !NOT_ALIAS_WORDS.some(w => this.isWord(w))) { alias = this.next().value; }
+      // 标准 SQL 要求 FROM 子查询必须带别名，这里放宽为自动生成，
+      // 避免 README 里 SELECT ... FROM (SELECT ...) 这类示例直接报错
+      if (!alias) alias = '__sub' + (++this.subquerySeq);
       return { subquery: sub, alias };
     }
     const table = this.parseTableName();
     let alias = null;
     // 这里排除的是"未进关键字表、但会跟在表名之后"的子句起始词，
     // 否则 `FROM t FETCH FIRST 10 ROWS ONLY` 会把 FETCH 当成表别名吃掉。
-    const NOT_ALIAS = ['JOIN', 'LEFT', 'RIGHT', 'FULL', 'WHERE', 'GROUP', 'ORDER', 'LIMIT',
-      'ON', 'HAVING', 'UNION', 'INNER', 'CROSS', 'OUTER', 'INTERSECT', 'EXCEPT',
-      'FETCH', 'RETURNING', 'WINDOW'];
     if (this.isKeyword('AS')) { this.next(); alias = this.parseAlias(); }
-    else if (this.peek().type === 'ident' && !NOT_ALIAS.some(w => this.isWord(w))) {
+    else if (this.peek().type === 'ident' && !NOT_ALIAS_WORDS.some(w => this.isWord(w))) {
       alias = this.next().value;
     }
     return { table, alias };
@@ -1096,9 +1312,28 @@ class Parser {
     const table = this.parseTableName();
     let where = null;
     if (this.isKeyword('WHERE')) { this.next(); where = this.parseExpr(); }
+    let orderBy = null, limit = null;
+    if (this.isKeyword('ORDER')) {
+      this.next(); this.expectKeyword('BY');
+      orderBy = [];
+      for (;;) {
+        const col = this.parseColumnRef();
+        let dir = 'asc';
+        if (this.isKeyword('ASC')) this.next();
+        else if (this.isKeyword('DESC')) { this.next(); dir = 'desc'; }
+        orderBy.push({ column: col, dir });
+        if (this.peek().type === 'op' && this.peek().value === ',') { this.next(); continue; }
+        break;
+      }
+    }
+    if (this.isKeyword('LIMIT')) {
+      this.next();
+      limit = this.parseValue();
+      if (typeof limit === 'number' && limit < 0) throw new Error(`LIMIT must be a non-negative integer, got ${limit}`);
+    }
     const returning = this.parseOptionalReturning();
     this.optionalTailSemicolon();
-    return { type: 'delete', table, where, returning };
+    return { type: 'delete', table, where, orderBy, limit, returning };
   }
 
   parseDropTable() {
@@ -1386,19 +1621,93 @@ class Parser {
     return this.parseOr();
   }
 
+  /**
+   * 函数实参用的表达式：与 parseExpr 相同，但叶子允许是"裸操作数"。
+   * 例如 IF(1 > 0, 'y', 'n') 的第一个参数是完整比较表达式，
+   * 而 IF(age, 'y', 'n') 这种裸列名也必须能解析。
+   */
+  parseArgExpr() {
+    this.bareExprDepth = (this.bareExprDepth || 0) + 1;
+    try {
+      return this.parseOr();
+    } finally {
+      this.bareExprDepth--;
+    }
+  }
+
+  // 位运算优先级（低 → 高）：|  <  ^  <  &  <  << >>  <  加减  <  乘除模
+  parseBitwise() {
+    let node = this.parseBitXor();
+    for (;;) {
+      const t = this.peek();
+      if (t.type === 'op' && t.value === '|') { this.next(); node = { type: 'arith', op: '|', left: node, right: this.parseBitXor() }; continue; }
+      break;
+    }
+    return node;
+  }
+
+  parseBitXor() {
+    let node = this.parseBitAnd();
+    for (;;) {
+      const t = this.peek();
+      if (t.type === 'op' && t.value === '^') { this.next(); node = { type: 'arith', op: '^', left: node, right: this.parseBitAnd() }; continue; }
+      break;
+    }
+    return node;
+  }
+
+  parseBitAnd() {
+    let node = this.parseShift();
+    for (;;) {
+      const t = this.peek();
+      if (t.type === 'op' && t.value === '&') { this.next(); node = { type: 'arith', op: '&', left: node, right: this.parseShift() }; continue; }
+      break;
+    }
+    return node;
+  }
+
+  parseShift() {
+    let node = this.parseAdditive();
+    for (;;) {
+      const t = this.peek();
+      if (t.type === 'op' && (t.value === '<<' || t.value === '>>')) {
+        this.next();
+        node = { type: 'arith', op: t.value, left: node, right: this.parseAdditive() };
+        continue;
+      }
+      break;
+    }
+    return node;
+  }
+
   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 };
@@ -1434,9 +1743,69 @@ class Parser {
     return this.parseComparison();
   }
 
+  /**
+   * 解析聚合调用：fn ( [DISTINCT] expr [, expr*] [ORDER BY ...] [SEPARATOR 'x'] )
+   * 以及 COUNT(*) 这类无参形式。
+   */
+  parseAggregateCall(fn) {
+    this.expect('op', '(');
+    const distinct = this.isKeyword('DISTINCT');
+    if (distinct) this.next();
+    let column = null;
+    let separator = null;
+    let innerOrder = null;
+    if (this.peek().type === 'op' && this.peek().value === '*') {
+      this.next();
+    } else if (!(this.peek().type === 'op' && this.peek().value === ')')) {
+      column = this.parseScalar();
+      // COUNT(DISTINCT a, b)：多列去重
+      if (distinct && this.peek().type === 'op' && this.peek().value === ',') {
+        const cols = [column];
+        while (this.peek().type === 'op' && this.peek().value === ',') {
+          this.next();
+          cols.push(this.parseScalar());
+        }
+        column = { type: 'tuple', items: cols };
+      } else if (this.peek().type === 'op' && this.peek().value === ',') {
+        // GROUP_CONCAT(expr, 'sep')
+        this.next();
+        separator = this.parseValue();
+      }
+      // GROUP_CONCAT(expr ORDER BY col [DESC])
+      if (this.isKeyword('ORDER')) {
+        this.next();
+        if (!this.isKeyword('BY')) throw new Error('Expected BY after ORDER in aggregate, got ' + "'" + this.peek().value + "'");
+        this.next();
+        innerOrder = [];
+        for (;;) {
+          const oCol = this.parseColumnRef();
+          let oDir = 'asc';
+          if (this.isKeyword('ASC')) this.next();
+          else if (this.isKeyword('DESC')) { this.next(); oDir = 'desc'; }
+          innerOrder.push({ column: oCol, dir: oDir });
+          if (this.peek().type === 'op' && this.peek().value === ',') { this.next(); continue; }
+          break;
+        }
+      }
+      // GROUP_CONCAT(expr SEPARATOR 'sep')
+      if (this.isWord('SEPARATOR')) {
+        this.next();
+        separator = this.parseValue();
+      }
+    }
+    this.expect('op', ')');
+    return this.parseOptionalOver({ type: 'aggregate', fn, column, distinct, separator, orderBy: innerOrder });
+  }
+
   parseOperand() {
     const t = this.next();
     if (t.type === 'ident') {
+      // 聚合函数名（GROUP_CONCAT / STDDEV / FIRST...）走 aggregate 节点，
+      // 否则会被当作逐行标量函数：既返回 null，又不会折叠分组
+      if (AGG_FUNCS.has(String(t.value).toUpperCase()) &&
+          this.peek().type === 'op' && this.peek().value === '(') {
+        return this.parseAggregateCall(String(t.value).toUpperCase());
+      }
       // 支持 alias.column 引用
       if (this.peek().type === 'op' && this.peek().value === '.') {
         this.next();
@@ -1469,6 +1838,60 @@ class Parser {
         this.expect('op', ')');
         return { type: 'cast', expr, dataType };
       }
+      // EXTRACT(YEAR FROM expr) —— 标准 SQL 的 FROM 形式
+      if (String(t.value).toUpperCase() === 'EXTRACT' && this.peek().type === 'op' && this.peek().value === '(') {
+        this.next();
+        const unitTok = this.next();
+        const unit = String(unitTok.value).toUpperCase();
+        if (!this.isWord('FROM')) throw new Error(`Expected FROM in EXTRACT, got '${this.peek().value}'`);
+        this.next();
+        const arg = this.parseOperand();
+        this.expect('op', ')');
+        return { type: 'func', name: 'EXTRACT', args: [{ type: 'value', value: unit }, arg] };
+      }
+      // SUBSTR(s FROM n [FOR m]) / TRIM([LEADING|TRAILING|BOTH] ['x'] FROM s)
+      if (['SUBSTR', 'SUBSTRING'].includes(String(t.value).toUpperCase()) && this.peek().type === 'op' && this.peek().value === '(') {
+        const name = String(t.value).toUpperCase();
+        this.next();
+        const s = this.parseOperand();
+        let fromV = null, forV = null;
+        if (this.isWord('FROM')) {
+          this.next();
+          fromV = this.parseOperand();
+          if (this.isWord('FOR')) { this.next(); forV = this.parseOperand(); }
+        } else if (this.peek().type === 'op' && this.peek().value === ',') {
+          this.next();
+          fromV = this.parseOperand();
+          if (this.peek().type === 'op' && this.peek().value === ',') { this.next(); forV = this.parseOperand(); }
+        }
+        this.expect('op', ')');
+        const args = [s];
+        if (fromV) args.push(fromV);
+        if (forV) args.push(forV);
+        return { type: 'func', name, args };
+      }
+      if (String(t.value).toUpperCase() === 'TRIM' && this.peek().type === 'op' && this.peek().value === '(') {
+        this.next();
+        let spec = null;
+        if (this.isWord('LEADING') || this.isWord('TRAILING') || this.isWord('BOTH')) {
+          spec = String(this.next().value).toUpperCase();
+        }
+        const first = this.parseOperand();
+        let target = null;
+        if (this.isWord('FROM')) {
+          this.next();
+          target = this.parseOperand();
+        } else if (this.peek().type === 'op' && this.peek().value === ',') {
+          this.next();
+          target = this.parseOperand();
+        }
+        this.expect('op', ')');
+        // 归一成 TRIM(target[, chars[, spec]])，与 applyScalarFunction 的既有签名兼容
+        if (target === null) return { type: 'func', name: 'TRIM', args: [first] };
+        const args = [target, first];
+        if (spec) args.push({ type: 'value', value: spec });
+        return { type: 'func', name: 'TRIM', args };
+      }
       // 函数调用: VERSION() / CONCAT(a, b) / NOW() ...
       if (this.peek().type === 'op' && this.peek().value === '(') {
         const name = t.value;
@@ -1477,7 +1900,42 @@ class Parser {
         if (!(this.peek().type === 'op' && this.peek().value === ')')) {
           for (;;) {
             if (this.peek().type === 'op' && this.peek().value === '*') { this.next(); args.push({ type: 'star' }); }
-            else args.push(this.parseOperand());
+            // INTERVAL n UNIT（DATE_ADD/DATE_SUB 用）
+            else if (this.isWord('INTERVAL')) {
+              this.next();
+              const nTok = this.peek();
+              let nVal;
+              if (nTok.type === 'op' && (nTok.value === '-' || nTok.value === '+')) {
+                this.next();
+                const numTok = this.next();
+                nVal = (nTok.value === '-' ? -1 : 1) * Number(numTok.value);
+              } else {
+                this.next();
+                nVal = Number(nTok.value);
+              }
+              const unitTok = this.next();
+              args.push({ type: 'interval', value: nVal, unit: String(unitTok.value).toUpperCase() });
+            }
+            // 实参允许完整的比较/布尔表达式，例如 IF(status = 'paid', amount, 0)
+            else args.push(this.parseArgExpr());
+            // GROUP_CONCAT(name ORDER BY age)：聚合函数内部的排序
+            if (this.isKeyword('ORDER')) {
+              this.next();
+              if (!this.isKeyword('BY')) throw new Error(`Expected BY after ORDER in aggregate, got '${this.peek().value}'`);
+              this.next();
+              const innerOrder = [];
+              for (;;) {
+                const oCol = this.parseColumnRef();
+                let oDir = 'asc';
+                if (this.isKeyword('ASC')) this.next();
+                else if (this.isKeyword('DESC')) { this.next(); oDir = 'desc'; }
+                innerOrder.push({ column: oCol, dir: oDir });
+                if (this.peek().type === 'op' && this.peek().value === ',') { this.next(); continue; }
+                break;
+              }
+              this.expect('op', ')');
+              return this.parseOptionalOver({ type: 'func', name, args, orderBy: innerOrder });
+            }
             if (this.peek().type === 'op' && this.peek().value === ',') { this.next(); continue; }
             break;
           }
@@ -1502,7 +1960,7 @@ class Parser {
       if (!(this.peek().type === 'op' && this.peek().value === ')')) {
         for (;;) {
           if (this.peek().type === 'op' && this.peek().value === '*') { this.next(); args.push({ type: 'star' }); }
-          else args.push(this.parseOperand());
+          else args.push(this.parseArgExpr());
           if (this.peek().type === 'op' && this.peek().value === ',') { this.next(); continue; }
           break;
         }
@@ -1510,14 +1968,13 @@ class Parser {
       this.expect('op', ')');
       return this.parseOptionalOver({ type: 'func', name, args });
     }
-    if (t.type === 'keyword' && ['SUM', 'AVG', 'MIN', 'MAX', 'COUNT'].includes(t.value)) {
-      const fn = t.value;
-      this.expect('op', '(');
-      let column = null;
-      if (this.peek().type === 'op' && this.peek().value === '*') { this.next(); }
-      else if (!(this.peek().type === 'op' && this.peek().value === ')')) column = this.parseScalar();
-      this.expect('op', ')');
-      return this.parseOptionalOver({ type: 'aggregate', fn, column });
+    if (AGG_FUNCS.has(String(t.value).toUpperCase()) &&
+        this.peek().type === 'op' && this.peek().value === '(') {
+      return this.parseAggregateCall(String(t.value).toUpperCase());
+    }
+    // 一元按位取反 ~x
+    if (t.type === 'op' && t.value === '~') {
+      return { type: 'bitnot', expr: this.parseOperand() };
     }
     if (t.type === 'op' && t.value === '(' && this.peek().type === 'keyword' && this.peek().value === 'SELECT') {
       const sub = this.parseSelect();
@@ -1532,8 +1989,8 @@ class Parser {
     throw new Error(`Expected value or column, got '${t.value}'`);
   }
 
-  // 算术表达式: + - * / % (左结合, * / 优先)
-  parseScalar() {
+  // 加减（左结合）
+  parseAdditive() {
     let node = this.parseTerm();
     for (;;) {
       const t = this.peek();
@@ -1545,6 +2002,16 @@ class Parser {
       }
       break;
     }
+    return node;
+  }
+
+  /**
+   * 标量表达式：算术 + 位运算，外加 IN / IS 后缀。
+   * 位运算要走到这里，否则 SELECT 列表里的 `SELECT 1 << 8` 无法解析
+   * （parseComparison 只在 WHERE 等布尔上下文被调用）。
+   */
+  parseScalar() {
+    let node = this.parseBitwise();
     // 后缀：expr IN (...)、expr IS [NOT] TRUE/FALSE/NULL（标量上下文，如 SELECT 1 IN (...))
     for (;;) {
       const t = this.peek();
@@ -1582,15 +2049,58 @@ 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;
+      }
       break;
     }
     return node;
@@ -1623,7 +2133,7 @@ class Parser {
   }
 
   parseComparison() {
-    const left = this.parseOperand();
+    const left = this.parseBitwise();
     const t = this.peek();
     let not = false;
     if (t.type === 'keyword' && t.value === 'NOT') {
@@ -1686,7 +2196,10 @@ 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 };
     }
 
     // MySQL 中 RLIKE 是 REGEXP 的同义词
@@ -1696,7 +2209,7 @@ class Parser {
       return { type: 'regexp', operand: left, pattern, not };
     }
 
-    if (t2.type === 'op' && ['=', '!=', '<>', '<', '<=', '>', '>='].includes(t2.value)) {
+    if (t2.type === 'op' && ['=', '!=', '<>', '<', '<=', '>', '>=', '<=>'].includes(t2.value)) {
       this.next();
       // = ANY (SELECT ...) / > ALL (SELECT ...)
       const anyAll = this.isWord('ANY') || this.isWord('ALL') || this.isWord('SOME');
@@ -1707,10 +2220,13 @@ class Parser {
         this.expect('op', ')');
         return { type: 'quantified', op: t2.value === '<>' ? '!=' : t2.value, operand: left, select: sub, quantifier, not };
       }
-      const right = this.parseOperand();
+      const right = this.parseBitwise();
       return { type: 'compare', op: t2.value === '<>' ? '!=' : t2.value, left, right };
     }
 
+    // 函数实参场景允许裸操作数（IF(age, ...) / SUM(IF(...)) 等）
+    if (this.bareExprDepth > 0) return left;
+
     throw new Error(`Expected comparison operator, got '${t2.value}'`);
   }
 }
@@ -1807,16 +2323,34 @@ 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);
+        case '^': return (Number(l) | 0) ^ (Number(r) | 0);
+        case '<<': return (Number(l) | 0) << (Number(r) | 0);
+        case '>>': return (Number(l) | 0) >> (Number(r) | 0);
       }
       return null;
     }
+    case 'bitnot':
+      return ~(Number(resolveOperand(operand.expr, row, ctx)) | 0);
     case 'func':
       return applyScalarFunction(operand, row, ctx);
     case 'case':
       return evaluateCaseVal(operand, row, ctx);
+    // 布尔类节点出现在"取值"位置时（如 IF(status = 'paid', ...)、SUM(IF(a > b,1,0))），
+    // 求值成 true/false 供上层按真值判断
+    case 'compare':
+    case 'and':
+    case 'or':
+    case 'xor':
+    case 'not':
     case 'in':
     case 'isNull':
     case 'isTruth':
+    case 'exists':
     case 'regexp':
     case 'like':
     case 'between':
@@ -1836,6 +2370,30 @@ 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 key = operand.key;
+      let v;
+      if (Array.isArray(base)) {
+        const idx = Number(key);
+        v = Number.isInteger(idx) ? (idx < 0 ? base[base.length + idx] : base[idx]) : undefined;
+      } else if (base && typeof base === 'object') {
+        v = base[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 'quantified': {
       // = ANY / > ALL (SELECT ...) —— 需先由执行层物化成 operand._list
       const v = resolveOperand(operand.operand, row, ctx);
@@ -1856,9 +2414,30 @@ function resolveOperand(operand, row, ctx) {
   }
 }
 
+/** 解析 SQL 里的日期文本（'YYYY-MM-DD' / 'YYYY-MM-DD HH:MM:SS' / Date） */
+function parseSqlDate(v) {
+  if (v === null || v === undefined) return null;
+  if (v instanceof Date) return Number.isNaN(v.getTime()) ? null : v;
+  const s = String(v).trim().replace(' ', 'T');
+  const d = new Date(s.length <= 10 ? s + 'T00:00:00' : s);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+function pad2(n) { return String(n).padStart(2, '0'); }
+
+/** 按输入形态回写日期：纯日期返回 YYYY-MM-DD，带时间返回 YYYY-MM-DD HH:MM:SS */
+function fmtSqlDate(dateOnly, d) {
+  const ymd = d.getFullYear() + '-' + pad2(d.getMonth() + 1) + '-' + pad2(d.getDate());
+  return dateOnly ? ymd : ymd + ' ' + pad2(d.getHours()) + ':' + pad2(d.getMinutes()) + ':' + pad2(d.getSeconds());
+}
+
 function applyScalarFunction(fnNode, row, ctx) {
   const name = (fnNode.name || '').toUpperCase();
-  const args = (fnNode.args || []).map(a => resolveOperand(a, row, ctx));
+  const rawArgs = fnNode.args || [];
+  // INTERVAL n UNIT 是语法结构而非普通值，原样传给 DATE_ADD / DATE_SUB
+  const args = rawArgs.map(a => (a && a.type === 'interval')
+    ? { __interval: true, value: a.value, unit: a.unit }
+    : resolveOperand(a, row, ctx));
   const session = ctx && ctx.session;
   if (ctx && ctx.functions && Object.prototype.hasOwnProperty.call(ctx.functions, name)) {
     return ctx.functions[name].apply(null, args);
@@ -1889,7 +2468,65 @@ function applyScalarFunction(fnNode, row, ctx) {
     case 'UPPER': case 'UCASE': return args[0] == null ? null : String(args[0]).toUpperCase();
     case 'LOWER': case 'LCASE': return args[0] == null ? null : String(args[0]).toLowerCase();
     case 'LENGTH': case 'CHAR_LENGTH': case 'CHARACTER_LENGTH': return args[0] == null ? null : String(args[0]).length;
-    case 'TRIM': return args[0] == null ? null : String(args[0]).trim();
+    // TRIM(s) / TRIM([LEADING|TRAILING|BOTH] chars FROM s) / TRIM(s, chars)
+    case 'TRIM': {
+      if (args[0] == null) return null;
+      const s = String(args[0]);
+      if (args.length === 1) return s.trim();
+      const chars = args[1] == null ? '' : String(args[1]);
+      if (!chars) return s.trim();
+      const spec = args[2] ? String(args[2]).toUpperCase() : 'BOTH';
+      const esc = chars.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const head = new RegExp('^[' + esc + ']+');
+      const tail = new RegExp('[' + esc + ']+$');
+      if (spec === 'LEADING') return s.replace(head, '');
+      if (spec === 'TRAILING') return s.replace(tail, '');
+      return s.replace(head, '').replace(tail, '');
+    }
+    // EXTRACT(YEAR FROM d) —— 解析层会把 unit 作为第一个参数传入
+    case 'EXTRACT': {
+      const unit = String(args[0] == null ? '' : args[0]).toUpperCase();
+      const d = parseSqlDate(args[1]);
+      if (!d) return null;
+      switch (unit) {
+        case 'YEAR': return d.getFullYear();
+        case 'MONTH': return d.getMonth() + 1;
+        case 'DAY': return d.getDate();
+        case 'HOUR': return d.getHours();
+        case 'MINUTE': return d.getMinutes();
+        case 'SECOND': return d.getSeconds();
+        case 'DOW': return d.getDay();              // 0 = 周日
+        case 'DAYOFWEEK': return d.getDay() + 1;    // 1 = 周日（MySQL 语义）
+        case 'WEEK': {
+          const start = new Date(d.getFullYear(), 0, 1);
+          return Math.floor((d - start) / 604800000) + 1;
+        }
+        default: return null;
+      }
+    }
+    case 'DATE_ADD': case 'ADDDATE':
+    case 'DATE_SUB': case 'SUBDATE': {
+      const sign = (name === 'DATE_SUB' || name === 'SUBDATE') ? -1 : 1;
+      const base = parseSqlDate(args[0]);
+      if (!base) return null;
+      const iv = args[1];
+      if (!iv || !iv.__interval) return fmtSqlDate(String(args[0]).length <= 10, base);
+      const isDateOnly = String(args[0]).trim().length <= 10;
+      const d = new Date(base.getTime());
+      const n = sign * Number(iv.value || 0);
+      switch (String(iv.unit || '').toUpperCase()) {
+        case 'DAY': case 'DAYS': d.setDate(d.getDate() + n); break;
+        case 'WEEK': case 'WEEKS': d.setDate(d.getDate() + n * 7); break;
+        case 'MONTH': case 'MONTHS': d.setMonth(d.getMonth() + n); break;
+        case 'QUARTER': d.setMonth(d.getMonth() + n * 3); break;
+        case 'YEAR': case 'YEARS': d.setFullYear(d.getFullYear() + n); break;
+        case 'HOUR': case 'HOURS': d.setHours(d.getHours() + n); break;
+        case 'MINUTE': case 'MINUTES': d.setMinutes(d.getMinutes() + n); break;
+        case 'SECOND': case 'SECONDS': d.setSeconds(d.getSeconds() + n); break;
+        default: return null;
+      }
+      return fmtSqlDate(isDateOnly, d);
+    }
     case 'LTRIM': return args[0] == null ? null : String(args[0]).replace(/^\s+/, '');
     case 'RTRIM': return args[0] == null ? null : String(args[0]).replace(/\s+$/, '');
     case 'ABS': return args[0] == null ? null : Math.abs(args[0]);
@@ -1975,13 +2612,25 @@ 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);
 }
 
 function extractEqualPushdown(expr, schema) {
@@ -2033,10 +2682,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）
@@ -2059,7 +2716,7 @@ 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':
@@ -2154,16 +2811,22 @@ function windowColumnValue(c, r) {
 
 function scalarColumnValue(c, r, ctx) {
   if (c.over || (c.scalar && c.scalar.over)) return windowColumnValue(c, r);
+  // 聚合列优先：GROUP_CONCAT / STDDEV 等同时带 scalar 与 aggregate
+  if (c.aggregate) {
+    return ctx._aggValue(ctx.group, c.aggregate || 'COUNT', c.column,
+      c.distinct, c.separator !== undefined ? c.separator : (c.scalar && c.scalar.separator),
+      c.orderBy || (c.scalar && c.scalar.orderBy));
+  }
   if (c.scalar) {
     const s = c.scalar;
     if (s && s.type === 'func' && ctx && ctx.ctxAggregates && Object.prototype.hasOwnProperty.call(ctx.ctxAggregates, String(s.name).toUpperCase())) {
       const fn = String(s.name).toUpperCase();
       const col = s.args && s.args[0];
-      return ctx._aggValue(ctx.group, fn, col);
+      return ctx._aggValue(ctx.group, fn, col, c.aggregate ? c.distinct : (c.scalar && c.scalar.distinct));
     }
     return resolveOperand(c.scalar, r, ctx);
   }
-  if (c.aggregate) return ctx._aggValue(ctx.group, c.aggregate || 'COUNT', c.column);
+  
   if (c.literal !== undefined) return c.literal;
   if (c.caseExpr) return evaluateCaseVal(c.caseExpr, r, ctx);
   if (c.expr === '*') return r[Object.keys(r).find(k => !k.startsWith('_'))];
@@ -2186,7 +2849,10 @@ function buildCreateTableSql(name, schema) {
     const seg = ['`' + col + '`', sqlTypeName(def.type)];
     if (def.autoIncrement) seg.push('AUTO_INCREMENT');
     if (def.nullable === false) seg.push('NOT NULL');
-    if (def.default !== undefined) seg.push('DEFAULT ' + (typeof def.default === 'string' ? "'" + def.default + "'" : def.default));
+    if (def.default !== undefined) {
+      // defaultExpr（CURRENT_TIMESTAMP 等）不加引号，普通字符串默认值才加
+      seg.push('DEFAULT ' + (typeof def.default === 'string' && !def.defaultExpr ? "'" + def.default + "'" : def.default));
+    }
     return seg.join(' ');
   });
   const pks = Object.keys(schema).filter(k => schema[k].primaryKey);
@@ -2353,7 +3019,23 @@ class SQLExecutor {
         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);
+          else if (statement.onDuplicate && schema) {
+            for (const [c, def] of Object.entries(schema)) {
+              if (def && def.unique && !def.primaryKey) 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();
@@ -2361,15 +3043,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);
@@ -2396,7 +3094,16 @@ class SQLExecutor {
               for (const { d, existingId } of conflicts) {
                 const data = {};
                 if (conflictSets) {
-                  for (const [col, val] of conflictSets) data[col] = val;
+                  for (const [col, val] of conflictSets) {
+                    // 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];
                 }
@@ -2525,6 +3232,52 @@ class SQLExecutor {
         delete this.engine._views[key];
         return { ok: true, type: 'dropView', message: `View '${statement.name}' dropped`, affectedRows: 0, warnings: [] };
       }
+      case 'createIndex': {
+        const tName = statement.table;
+        if (typeof this.engine.hasTable === 'function' && !this.engine.hasTable(tName)) {
+          throw new Error(`Table '${tName}' does not exist`);
+        }
+        let handled = false;
+        if (typeof this.engine.createIndex === 'function') {
+          await this.engine.createIndex(tName, statement.columns, { unique: statement.unique, name: statement.name });
+          handled = true;
+        } else if (typeof this.engine._ensureTable === 'function') {
+          const tbl = this.engine._ensureTable(tName) || (this.engine._tables && this.engine._tables[tName]);
+          if (tbl && typeof tbl.createIndex === 'function') {
+            // Table.createIndex 目前是单字段接口，复合索引按逐列建
+            for (const col of statement.columns) tbl.createIndex(col);
+            handled = true;
+          }
+        }
+        if (!handled) {
+          throw new Error(
+            `CREATE INDEX is not supported by this engine (no createIndex/_ensureTable on the engine object)`
+          );
+        }
+        return {
+          ok: true, type: 'createIndex', table: tName, name: statement.name,
+          affectedRows: 0, warnings: [],
+          message: `Index '${statement.name}' created on ${tName}(${statement.columns.join(', ')})`,
+        };
+      }
+      case 'dropIndex': {
+        const tName2 = statement.table;
+        let handled = false;
+        if (typeof this.engine.dropIndex === 'function') {
+          await this.engine.dropIndex(tName2, statement.name);
+          handled = true;
+        } else if (tName2 && typeof this.engine._ensureTable === 'function') {
+          const tbl = this.engine._ensureTable(tName2) || (this.engine._tables && this.engine._tables[tName2]);
+          if (tbl && typeof tbl.dropIndex === 'function') { tbl.dropIndex(statement.name); handled = true; }
+        }
+        if (!handled) {
+          if (statement.ifExists) {
+            return { ok: true, type: 'dropIndex', affectedRows: 0, skipped: true, warnings: [], message: `Index '${statement.name}' did not exist` };
+          }
+          throw new Error(`DROP INDEX is not supported by this engine (no dropIndex on the engine/table object)`);
+        }
+        return { ok: true, type: 'dropIndex', table: tName2, name: statement.name, affectedRows: 0, warnings: [], message: `Index '${statement.name}' dropped` };
+      }
       case 'savepoint': {
         // 引擎侧没有保存点/快照能力。这里只登记名字，绝不假装能回滚。
         if (!this.engine._savepoints) this.engine._savepoints = new Set();
@@ -2582,11 +3335,27 @@ class SQLExecutor {
         const all = (await this.engine.find(statement.table, {}, { limit: 1e9, offset: 0 })).map(r => normalizeRow(r, schema));
         const ids = [];
         const removedRows = [];
-        for (const row of all) {
-          if (!statement.where || evaluateExpr(statement.where, row, this.ctx)) {
-            const id = this._rowPkId(row, pkCols);
-            if (id !== undefined) { ids.push(id); removedRows.push(row); }
-          }
+        let candidates = all.filter(row => !statement.where || evaluateExpr(statement.where, row, this.ctx));
+        // DELETE ... ORDER BY ... LIMIT n
+        if (statement.orderBy) {
+          const cmp = (a, b) => {
+            for (const o of statement.orderBy) {
+              const av = resolveOperand({ type: 'column', name: o.column }, a, this.ctx);
+              const bv = resolveOperand({ type: 'column', name: o.column }, b, this.ctx);
+              if (av === bv) continue;
+              if (av === undefined || av === null) return o.dir === 'asc' ? -1 : 1;
+              if (bv === undefined || bv === null) return o.dir === 'asc' ? 1 : -1;
+              const d = typeof av === 'number' && typeof bv === 'number' ? av - bv : String(av).localeCompare(String(bv));
+              if (d !== 0) return o.dir === 'asc' ? d : -d;
+            }
+            return 0;
+          };
+          candidates = candidates.slice().sort(cmp);
+        }
+        if (typeof statement.limit === 'number') candidates = candidates.slice(0, statement.limit);
+        for (const row of candidates) {
+          const id = this._rowPkId(row, pkCols);
+          if (id !== undefined) { ids.push(id); removedRows.push(row); }
         }
         if (ids.length > 0) {
           if (this.engine.removeByIds) await this.engine.removeByIds(statement.table, ids);
@@ -3114,12 +3883,28 @@ class SQLExecutor {
     return out;
   }
 
-  _aggValue(rows, fn, column) {
-    if (fn === 'COUNT') return rows.length;
+  _aggValue(rows, fn, column, distinct, separator, orderBy) {
     const op = typeof column === 'string' ? { type: 'column', name: column } : column;
-    const values = op && op.type === 'star'
+    // COUNT(*) / COUNT()：参数为 star 或缺失，直接按行数算
+    const noColumn = !op || op.type === 'star';
+    let values = noColumn
       ? rows.map(r => 1)
-      : rows.map(r => resolveOperand(op, r, this.ctx)).filter(v => v !== null && v !== undefined);
+      : op && op.type === 'tuple'
+        // COUNT(DISTINCT a, b)：先把多列拼成元组再聚合
+        ? rows.map(r => JSON.stringify(op.items.map(it => resolveOperand(it, r, this.ctx))))
+          .filter(v => v !== null && v !== undefined)
+        : rows.map(r => resolveOperand(op, r, this.ctx)).filter(v => v !== null && v !== undefined);
+    // COUNT(DISTINCT x) / SUM(DISTINCT x)：先按值去重再聚合
+    if (distinct) {
+      const seen = new Set();
+      values = values.filter(v => {
+        const k = typeof v === 'object' ? JSON.stringify(v) : String(v);
+        if (seen.has(k)) return false;
+        seen.add(k);
+        return true;
+      });
+    }
+    if (fn === 'COUNT') return values.length;
     if (this.ctx && this.ctx.aggregates && Object.prototype.hasOwnProperty.call(this.ctx.aggregates, fn)) {
       const agg = this.ctx.aggregates[fn];
       if (typeof agg === 'function') {
@@ -3135,6 +3920,54 @@ class SQLExecutor {
     if (fn === 'AVG') return values.length ? values.reduce((s, v) => s + (typeof v === 'number' ? v : Number(v) || 0), 0) / values.length : null;
     if (fn === 'MIN') return values.length ? Math.min(...values.map(v => Number(v))) : null;
     if (fn === 'MAX') return values.length ? Math.max(...values.map(v => Number(v))) : null;
+    if (fn === 'FIRST') return values.length ? values[0] : null;
+    if (fn === 'LAST') return values.length ? values[values.length - 1] : null;
+    if (fn === 'GROUP_CONCAT') {
+      let src = rows;
+      // GROUP_CONCAT(expr ORDER BY col [DESC])：先按内部排序键排好行，再取值拼接
+      if (orderBy && orderBy.length) {
+        const cmp = (a, b) => {
+          for (const o of orderBy) {
+            const av = resolveOperand({ type: 'column', name: o.column }, a, this.ctx);
+            const bv = resolveOperand({ type: 'column', name: o.column }, b, this.ctx);
+            if (av === bv) continue;
+            if (av === null || av === undefined) return o.dir === 'asc' ? 1 : -1;
+            if (bv === null || bv === undefined) return o.dir === 'asc' ? -1 : 1;
+            const d = (typeof av === 'number' && typeof bv === 'number')
+              ? av - bv : String(av).localeCompare(String(bv));
+            if (d !== 0) return o.dir === 'asc' ? d : -d;
+          }
+          return 0;
+        };
+        src = rows.slice().sort(cmp);
+      }
+      const parts = src.map(r => resolveOperand(op, r, this.ctx));
+      let joined = parts.filter(v => v !== null && v !== undefined);
+      if (distinct) {
+        const seen = new Set();
+        joined = joined.filter(v => {
+          const k = typeof v === 'object' ? JSON.stringify(v) : String(v);
+          if (seen.has(k)) return false;
+          seen.add(k);
+          return true;
+        });
+      }
+      if (joined.length === 0) return null;
+      const sep = (separator !== undefined && separator !== null) ? String(separator) : ',';
+      return joined.map(v => (v === null || v === undefined ? '' : String(v))).join(sep);
+    }
+    // 标准差 / 方差族：_POP 为总体、_SAMP（及无后缀 VAR/STDDEV）为样本
+    if (fn === 'STDDEV' || fn === 'STDDEV_POP' || fn === 'STDDEV_SAMP' ||
+        fn === 'VARIANCE' || fn === 'VAR_POP' || fn === 'VAR_SAMP') {
+      const nums = values.map(v => Number(v)).filter(v => Number.isFinite(v));
+      if (nums.length === 0) return null;
+      const pop = (fn === 'STDDEV_POP' || fn === 'VAR_POP');
+      const mean = nums.reduce((s, v) => s + v, 0) / nums.length;
+      const denom = pop ? nums.length : nums.length - 1;   // 样本方差用 n-1
+      if (denom <= 0) return null;
+      const variance = nums.reduce((s, v) => s + (v - mean) * (v - mean), 0) / denom;
+      return fn.indexOf('STDDEV') === 0 ? Math.sqrt(variance) : variance;
+    }
     return null;
   }
 
@@ -3142,7 +3975,7 @@ class SQLExecutor {
     if (!node || typeof node !== 'object') return;
     if (node.type === 'aggregate') {
       node.type = 'value';
-      node.value = this._aggValue(group, node.fn, node.column);
+      node.value = this._aggValue(group, node.fn, node.column, node.distinct, node.separator, node.orderBy);
       delete node.fn;
       delete node.column;
       return;
@@ -3211,6 +4044,61 @@ class SQLExecutor {
     return out;
   }
 
+  /**
+   * 校验语句里引用的列是否真实存在。
+   * 之前 `SELECT nosuchcol FROM t` 会静默返回 null 而不是报错 —— 调用方拿到的
+   * 是"一列 null"，往往被当成"数据为空"，比直接报 no such column 更难排查。
+   *
+   * 只在能确定列名集合时校验（取样本行的键），空表不敢断言，宁可不报。
+   * 不深入子查询节点：它们有自己的 FROM，列属于另一个作用域。
+   */
+  _validateColumnRefs(statement, rows) {
+    if (!statement || !Array.isArray(rows) || rows.length === 0) return;
+    const sample = rows[0];
+    if (!sample || typeof sample !== 'object') return;
+    const known = new Set();
+    for (const k of Object.keys(sample)) known.add(String(k).toLowerCase());
+    // HAVING / ORDER BY 允许引用 SELECT 的输出别名（如 HAVING cnt >= 1），
+    // 这些名字不在表里，必须一并视为已知，否则会误报 no such column
+    if (Array.isArray(statement.columns)) {
+      for (const c of statement.columns) {
+        if (c && typeof c.alias === 'string' && c.alias) known.add(c.alias.toLowerCase());
+      }
+    }
+
+    const walk = (node) => {
+      if (!node || typeof node !== 'object') return;
+      if (Array.isArray(node)) { for (const n of node) walk(n); return; }
+      // 子查询/嵌套 SELECT 有自己的表，跳过
+      if (node.type === 'select' || node.type === 'subquery') return;
+      if (node.type === 'column' && typeof node.name === 'string') {
+        const n = node.name.toLowerCase();
+        const base = n.indexOf('.') >= 0 ? n.slice(n.indexOf('.') + 1) : n;
+        if (!known.has(n) && !known.has(base)) {
+          throw new Error(`no such column: ${node.name}`);
+        }
+      }
+      for (const k of Object.keys(node)) {
+        if (k === 'select' || k === 'subquery') continue;
+        walk(node[k]);
+      }
+    };
+
+    walk(statement.columns);
+    walk(statement.where);
+    walk(statement.having);
+    walk(statement.orderBy);
+    if (Array.isArray(statement.groupBy)) {
+      // groupBy 是列名字符串数组
+      for (const g of statement.groupBy) {
+        if (typeof g !== 'string') continue;
+        const n = g.toLowerCase();
+        const base = n.indexOf('.') >= 0 ? n.slice(n.indexOf('.') + 1) : n;
+        if (!known.has(n) && !known.has(base)) throw new Error(`no such column: ${g}`);
+      }
+    }
+  }
+
   /** 收集子树里所有列名（含限定形式 alias.col） */
   _collectColumnNames(node, out = []) {
     if (!node || typeof node !== 'object') return out;
@@ -3446,7 +4334,7 @@ class SQLExecutor {
             case 'MAX': {
               const f = frameIdx(pos);
               const slice = ordered.slice(f.start, f.end + 1).map(i => rows[i]);
-              v = this._aggValue(slice, w.fn, argNode);
+              v = this._aggValue(slice, w.fn, argNode, !!(w.spec && w.spec.distinct), w.spec && w.spec.separator);
               break;
             }
             default: v = null;
@@ -3639,6 +4527,7 @@ class SQLExecutor {
     }
 
     let rows = all;
+    this._validateColumnRefs(statement, rows);
     if (statement.where) {
       // 相关子查询：必须逐行重新求值，否则外层引用拿不到当前行的值
       const outerAliases = this._outerAliases(statement);
@@ -3681,7 +4570,7 @@ class SQLExecutor {
         for (const c of statement.columns) {
           if (c.aggregate) {
             const group = r._group || [r];
-            const v = this._aggValue(group, c.aggregate || 'COUNT', c.column);
+            const v = this._aggValue(group, c.aggregate || 'COUNT', c.column, c.distinct, c.separator, c.orderBy);
             ctx['__agg_' + (c.alias || c.column || 'COUNT(*)')] = v;
             if (c.column) ctx[c.column] = v;
             if (c.alias) ctx[c.alias] = v;
@@ -3702,7 +4591,7 @@ class SQLExecutor {
         const key = JSON.stringify(statement.columns.map(c => {
           if (c.scalar) return resolveOperand(c.scalar, r, this.ctx);
           if (c.caseExpr) return evaluateCaseVal(c.caseExpr, r);
-          if (c.aggregate) return this._aggValue(r._group || [r], c.aggregate || 'COUNT', c.column);
+          if (c.aggregate) return this._aggValue(r._group || [r], c.aggregate || 'COUNT', c.column, c.distinct, c.separator, c.orderBy);
           return resolveOperand({ type: 'column', name: c.expr }, r, this.ctx);
         }));
         if (seen.has(key)) return false;
@@ -3717,7 +4606,7 @@ class SQLExecutor {
     if (!statement.groupBy && (statement.columns.some(c => c.aggregate && !c.window) || hasCustomAgg)) {
       const cols = statement.columns.map(c => scalarColumnName(c));
       const valueOf = (c) => {
-        if (c.aggregate) return this._aggValue(rows, c.aggregate || 'COUNT', c.column);
+        if (c.aggregate) return this._aggValue(rows, c.aggregate || 'COUNT', c.column, c.distinct, c.separator, c.orderBy);
         if (c.scalar && c.scalar.type === 'func' && hasCustomAgg) {
           const fn = String(c.scalar.name).toUpperCase();
           if (Object.prototype.hasOwnProperty.call(this.ctx.aggregates, fn)) {
@@ -3986,6 +4875,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。
@@ -4035,7 +4962,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;
 }