jsql-neo 6.1.0 → 6.2.0

package/README.md

@@ -835,7 +835,7 @@ CREATE TABLE IF NOT EXISTS orders (
 
 **SELECT grammar**
 
-```sql
+```text
 WITH [RECURSIVE] cte_name [(col, ...)] AS (SELECT ...)[, ...]   -- CTE，见下节
 SELECT [DISTINCT] select_list
 FROM table_reference
@@ -1102,14 +1102,14 @@ ORDER BY avg_sal DESC;
 
 **Bitwise** — `& | ^ ~ << >>`（`^` 是按位异或，`~` 是按位取反）。
 
-> **运算符方言说明。** `^` 与 `~` 在 MySQL（位运算）和 PostgreSQL（`^` 为幂、
-> `~` 为正则匹配）中含义冲突，本实现统一采用 **MySQL 语义**：`^` = 按位异或、
-> `~` = 按位取反。需要幂运算请用 `POWER(x, n)`，需要正则请用 `REGEXP`。
-> 因此 PG 风格的 `^`（幂）与 `~ ~* !~ !~*`（正则）**暂不支持**。
+> **运算符方言说明。** `^` 与 `~` 在 MySQL 与 PostgreSQL 中含义冲突，本实现按上下文区分：
+> - `^` 统一为**按位异或**（MySQL 语义）；幂运算请用 `POWER(x, n)`。
+> - `~` 在**单目**位置是按位取反（MySQL），在**双目**位置是正则匹配（PG），
+>   另有 `~*`（不敏感）、`!~`、`!~*`。
+> - 需要正则时也可用 `REGEXP` / `RLIKE`；PG 的 `^`（幂）**暂不支持**。
 
-**JSON (PG style)** — `->`（返回 JSON）、`->>`（返回文本），可链式
-（`meta->'addr'->>'city'`）。`#>` `#>>`（路径）、`@>` `<@`（包含）、
-`?` `?|` `?&`（键存在）**暂不支持**。
+**JSON (PG style)** — `->` / `->>`（取字段）、`#>` / `#>>`（路径取值）、`@>` / `<@`（包含）、
+`?` / `?|` / `?&`（键存在），可链式（`meta->'addr'->>'city'`）。
 
 ### LIKE / ILIKE / regex
 
@@ -1162,7 +1162,7 @@ INSERT INTO users (id, meta) VALUES
   (1, '{"name":"Alice","tags":["admin","ops"],"addr":{"city":"SH"}}');
 
 SELECT meta->>'name' AS name, meta->'addr'->>'city' AS city
-FROM users;
+FROM users WHERE meta @> '{"tags":["admin"]}';
 ```
 
 JSON columns are fully interoperable with Mongo document views.
@@ -3138,7 +3138,7 @@ DELETE FROM orders WHERE status = 'cancelled' LIMIT 100;
 
 #### 查询语法 SELECT
 
-```sql
+```text
 SELECT [DISTINCT] select_list
 FROM table_reference
 [JOIN table_reference ON condition]
@@ -3445,11 +3445,16 @@ INTERVAL 单位：`DAY` `HOUR` `MINUTE` `SECOND` `WEEK` `MONTH` `YEAR` 及其组
 |---|---|---|
 | `->` | 取 JSON 字段（返回 JSON） | `meta->'name'` |
 | `->>` | 取 JSON 字段（返回文本） | `meta->>'name'` |
+| `#>` | 路径取值（返回 JSON） | `meta#>'{addr,city}'` |
+| `#>>` | 路径取值（返回文本） | `meta#>>'{addr,city}'` |
+| `@>` | 包含 | `meta @> '{"plan":"pro"}'` |
+| `<@` | 被包含 | `'{"a":1}' <@ meta` |
+| `?` | 含指定键 | `meta ? 'plan'` |
+| `?\|` | 含任一键 | `meta ?\| '{a,b}'` |
+| `?&` | 含全部键 | `meta ?& '{a,b}'` |
 
 可链式取值：`meta->'addr'->>'city'`。
 
-> `#>` `#>>`（路径访问）、`@>` `<@`（包含）、`?` `?|` `?&`（键存在）**暂不支持** —— 使用时会抛出明确错误，不会静默退化成别的运算。
-
 ### LIKE / ILIKE / 正则
 
 **LIKE 通配符**
@@ -3466,8 +3471,8 @@ INTERVAL 单位：`DAY` `HOUR` `MINUTE` `SECOND` `WEEK` `MONTH` `YEAR` 及其组
 
 - 基于 JS RegExp 引擎
 - 支持 flags：`i`（忽略大小写）、`m`（多行）、`s`（点匹配换行）
-- PG 风格的 `~` / `~*` / `!~` / `!~*` 运算符**暂不支持**（`~` 已被用作按位取反）。
-  正则匹配请用 `REGEXP` / `RLIKE`。
+- PG 风格的 `~`（大小写敏感）/ `~*`（不敏感）/ `!~` / `!~*` 双目运算符也支持；
+  单目位置的 `~` 仍是按位取反。
 
 ```sql
 SELECT * FROM users
@@ -3570,7 +3575,7 @@ INSERT INTO users (id, meta) VALUES
 -- 查询路径
 SELECT meta->>'name' AS name,
        meta->'addr'->>'city' AS city
-FROM users;
+FROM users WHERE meta @> '{"tags":["admin"]}';
 ```
 
 JSON 函数见 [系统与杂项函数](#系统与杂项函数)。Mongo 客户端视角下，JSON 列与 BSON 文档完全互通。
@@ -5798,6 +5803,8 @@ expr := literal
       | expr [NOT] LIKE pattern [ESCAPE char]
       | expr [NOT] ILIKE pattern
       | expr [NOT] RLIKE pattern | expr [NOT] REGEXP pattern
+      | expr ~ pattern | expr ~* pattern | expr !~ pattern | expr !~* pattern
+      | expr ? key | expr ?| keys | expr ?& keys
       | expr IS [NOT] NULL | expr IS [NOT] TRUE | expr IS [NOT] FALSE
       | expr [NOT] IN ( ... )
       | expr [NOT] ANY '(' select_statement ')'
@@ -5843,12 +5850,12 @@ function_call := func_name '(' [DISTINCT] args ')'      -- 普通/聚合
 ### 运算符优先级（从高到低）
 
 ```
-1.  ()  .  []  ->  ->>  ::
+1.  ()  .  []  ->  ->>  #>  #>>  ::
 2.  CAST 一元 + - ~
 3.  ^  *  /  %  DIV  MOD
 4.  +  -
 5.  <<  >>  &  |  ^（位）
-6.  =  <>  !=  <  <=  >  >=  <=>  BETWEEN  IN  LIKE  ILIKE  RLIKE  REGEXP
+6.  =  <>  !=  <  <=  >  >=  <=>  @>  <@  ?  ?|  ?&  BETWEEN  IN  LIKE  ILIKE  RLIKE  REGEXP  ~  ~*  !~  !~*
 7.  NOT
 8.  AND  &&
 9.  XOR
@@ -7445,12 +7452,12 @@ jsql import ./data app.sql
 | 冲突处理 | `ON DUPLICATE KEY UPDATE` | `ON CONFLICT ... DO ...` | 两者都支持 |
 | 占位符 | `?` | `$1, $2` | 两者（分协议） |
 | 模糊匹配 | `LIKE`（大小写敏感） | `LIKE` + `ILIKE` | 两者 |
-| 正则 | `REGEXP` | `REGEXP` | 两者 + `RLIKE` |
+| 正则 | `REGEXP` | `~` `~*` | 两者 + `RLIKE` |
 | 标识符引用 | 反引号 `` ` `` | 双引号 `"` | 两者 |
 | 字符串字面量 | 单引号 | 单引号 | 单引号（双引号按标识符，PG 语义） |
 | 布尔 | `TRUE/FALSE`（1/0） | `t/f`（三值逻辑） | 兼容两者 |
 | 分页 | `LIMIT off, n` | `LIMIT n OFFSET off` | 两者 |
-| JSON 访问 | `JSON_EXTRACT` | `->` `->>` | 两者 |
+| JSON 访问 | `JSON_EXTRACT` | `->` `->>` `#>>` | 两者 |
 | 类型转换 | `CAST`/`CONVERT` | `::` | 三者 |
 | 条件分支 | `IF()` | `CASE` | `IF` + `CASE` + `IIF` |
 | 空值回退 | `IFNULL()` | `COALESCE` | 两者 |

package/lib/migrate.js

@@ -12,6 +12,15 @@ const path = require('path');
 const { splitStatements, executeSQL } = require('./sql');
 const { parseFieldShorthand } = require('./database');
 
+// 体积护栏（CWE-770）：与 lib/sql.js 的 DEFAULT_MAX_SQL_LENGTH 同风格。
+// 可用 opts.maxInputSize / opts.maxRows 覆盖；传 Infinity 关闭；chunkSize 控制每批 insert 行数。
+const DEFAULT_MAX_CSV_LENGTH = 64 * 1024 * 1024;  // 64 MiB
+const DEFAULT_MAX_JSON_LENGTH = 64 * 1024 * 1024;
+const DEFAULT_MAX_SQL_LENGTH = 64 * 1024 * 1024;  // 与 lib/sql.js 保持一致
+const DEFAULT_MAX_ROWS = 2_000_000;             // 200 万行
+const DEFAULT_MAX_STATEMENTS = 200_000;          // dump 文件最多允许 20 万条语句
+const DEFAULT_CHUNK_SIZE = 1000;
+
 function normalizeSchema(schema) {
   const out = {};
   for (const [name, def] of Object.entries(schema || {})) {
@@ -52,10 +61,31 @@ function parseValue(str, type) {
   return str;
 }
 
-function parseCSV(text) {
+function parseCSV(text, opts = {}) {
+  if (typeof text !== 'string') {
+    throw new Error('parseCSV: csv must be a string');
+  }
+  const maxLen = opts.maxInputSize == null ? DEFAULT_MAX_CSV_LENGTH : opts.maxInputSize;
+  if (typeof maxLen === 'number' && Number.isFinite(maxLen) && text.length > maxLen) {
+    throw new Error(
+      `CSV text too large: ${text.length} chars exceeds limit of ${maxLen} ` +
+      `(raise opts.maxInputSize to allow larger input)`
+    );
+  }
+  const maxRows = opts.maxRows == null ? DEFAULT_MAX_ROWS : opts.maxRows;
+  const isFiniteMaxRows = typeof maxRows === 'number' && Number.isFinite(maxRows);
+
   const rows = [];
+  // 把 `field += c` 改为数组收集中间 join —— 与 splitStatements 同修 O(n²)
+  let fieldBuf = [];
+  const flushField = () => { const s = fieldBuf.join(''); fieldBuf.length = 0; return s; };
   let row = [];
-  let field = '';
+  const flushRow = () => {
+    const r = row;
+    row = [];
+    rows.push(r);
+    return r;
+  };
   let inQuotes = false;
   let i = 0;
   const n = text.length;
@@ -63,32 +93,48 @@ function parseCSV(text) {
     const c = text[i];
     if (inQuotes) {
       if (c === '"') {
-        if (text[i + 1] === '"') { field += '"'; i += 2; continue; }
+        if (text[i + 1] === '"') { fieldBuf.push('"'); i += 2; continue; }
         inQuotes = false;
         i++;
         continue;
       }
-      field += c;
+      fieldBuf.push(c);
       i++;
       continue;
     }
-    if (c === '"' && field === '') { inQuotes = true; i++; continue; }
-    if (c === ',') { row.push(field); field = ''; i++; continue; }
+    if (c === '"' && fieldBuf.length === 0) { inQuotes = true; i++; continue; }
+    if (c === ',') { row.push(flushField()); i++; continue; }
     if (c === '\n' || c === '\r') {
       if (c === '\r' && text[i + 1] === '\n') i++;
-      row.push(field);
-      field = '';
-      if (row.length > 1 || row[0] !== '') rows.push(row);
-      row = [];
+      row.push(flushField());
+      if (row.length > 1 || row[0] !== '') {
+        if (isFiniteMaxRows && rows.length + 1 > maxRows) {
+          throw new Error(
+            `CSV too many rows: ${rows.length + 1} exceeds limit of ${maxRows} ` +
+            `(raise opts.maxRows or split the file)`
+          );
+        }
+        flushRow();
+      } else {
+        row = [];
+      }
       i++;
       continue;
     }
-    field += c;
+    fieldBuf.push(c);
     i++;
   }
-  if (field !== '' || row.length > 0) {
-    row.push(field);
-    if (row.length > 1 || row[0] !== '') rows.push(row);
+  if (fieldBuf.length > 0 || row.length > 0) {
+    row.push(flushField());
+    if (row.length > 1 || row[0] !== '') {
+      if (isFiniteMaxRows && rows.length + 1 > maxRows) {
+        throw new Error(
+          `CSV too many rows: ${rows.length + 1} exceeds limit of ${maxRows} ` +
+          `(raise opts.maxRows or split the file)`
+        );
+      }
+      flushRow();
+    }
   }
   return rows;
 }
@@ -123,7 +169,23 @@ async function exportAllToJSON(engine, tables) {
 
 async function importFromJSON(engine, data, opts = {}) {
   const overwrite = !!(opts && opts.overwrite);
-  let tables = typeof data === 'string' ? JSON.parse(data) : data;
+  let tables;
+  if (typeof data === 'string') {
+    // JSON.parse 吞超长输入也会打爆堆 —— 先加体积护栏，错误带位置
+    const maxLen = opts.maxInputSize == null ? DEFAULT_MAX_JSON_LENGTH : opts.maxInputSize;
+    if (typeof maxLen === 'number' && Number.isFinite(maxLen) && data.length > maxLen) {
+      throw new Error(
+        `JSON text too large: ${data.length} chars exceeds limit of ${maxLen} ` +
+        `(raise opts.maxInputSize to allow larger input)`
+      );
+    }
+    try { tables = JSON.parse(data); }
+    catch (e) {
+      throw new Error(`importFromJSON: invalid JSON: ${e.message}`);
+    }
+  } else {
+    tables = data;
+  }
   // 兼容单表形状：exportTableToJSON 返回 { table, schema, rows }
   if (tables && !Array.isArray(tables) && typeof tables === 'object'
       && tables.table && tables.schema && !tables[tables.table]) {
@@ -142,8 +204,13 @@ async function importFromJSON(engine, data, opts = {}) {
     await engine.createTable(name, normalizeSchema(t.schema));
     created.push(name);
     if (Array.isArray(t.rows) && t.rows.length > 0) {
-      const ids = await engine.insert(name, t.rows.map(r => ({ ...r })));
-      inserted += Array.isArray(ids) ? ids.length : t.rows.length;
+      // 分块 insert —— 避免全量 rows.map 先攒再 insert
+      const chunkSize = opts.chunkSize != null ? opts.chunkSize : DEFAULT_CHUNK_SIZE;
+      for (let i = 0; i < t.rows.length; i += chunkSize) {
+        const chunk = t.rows.slice(i, i + chunkSize).map(r => ({ ...r }));
+        const ids = await engine.insert(name, chunk);
+        inserted += Array.isArray(ids) ? ids.length : chunk.length;
+      }
     }
   }
   return { created, inserted };
@@ -161,7 +228,8 @@ async function exportTableToCSV(engine, table) {
 
 async function importFromCSV(engine, table, csv, opts = {}) {
   const schema = opts.schema || await engine.getTableSchema(table);
-  const rows = parseCSV(csv);
+  // parseCSV 内已有体积/行数护栏，这里传 opts.maxInputSize / opts.maxRows
+  const rows = parseCSV(csv, opts);
   if (rows.length === 0) return { inserted: 0 };
   let columns;
   let start = 0;
@@ -179,24 +247,43 @@ async function importFromCSV(engine, table, csv, opts = {}) {
     }
     await engine.createTable(table, normalizeSchema(schema));
   }
-  const dataRows = [];
-  for (let i = start; i < rows.length; i++) {
-    const row = {};
-    for (let j = 0; j < columns.length; j++) {
-      const type = schema && schema[columns[j]] ? schema[columns[j]].type : 'string';
-      row[columns[j]] = parseValue(rows[i][j], type);
-    }
-    if (row.id === null || row.id === undefined || row.id === '') delete row.id;
-    dataRows.push(row);
+  const chunkSize = opts.chunkSize != null ? opts.chunkSize : DEFAULT_CHUNK_SIZE;
+  let inserted = 0;
+  // 不攒 dataRows 全量，边解析边分块写入 —— 避免 2M 行全在内存里
+  for (let i = start; i < rows.length; i += chunkSize) {
+    const chunk = rows.slice(i, i + chunkSize);
+    const dataRows = chunk.map(raw => {
+      const row = {};
+      for (let j = 0; j < columns.length; j++) {
+        const type = schema && schema[columns[j]] ? schema[columns[j]].type : 'string';
+        row[columns[j]] = parseValue(raw[j], type);
+      }
+      if (row.id === null || row.id === undefined || row.id === '') delete row.id;
+      return row;
+    });
+    const ids = await engine.insert(table, dataRows);
+    inserted += Array.isArray(ids) ? ids.length : dataRows.length;
   }
-  const ids = dataRows.length > 0 ? await engine.insert(table, dataRows) : [];
-  return { inserted: dataRows.length, ids };
+  return { inserted };
 }
 
 /* ---------- mysqldump ---------- */
 
 async function importDump(engine, sqlText, opts = {}) {
-  const statements = splitStatements(sqlText);
+  // splitStatements 自身有体积护栏，但这里要让用户能通过 opts.maxInputSize 覆盖，
+  // 还要额外加「语句数量」护栏 —— 64 MiB 里可能塞几百万条小 INSERT，每条都合法但合起来打爆堆。
+  const maxLen = opts.maxInputSize == null ? DEFAULT_MAX_SQL_LENGTH : opts.maxInputSize;
+  const splitOpts = { maxLength: maxLen };
+  const statements = splitStatements(sqlText, splitOpts);
+
+  const maxStmts = opts.maxStatements == null ? DEFAULT_MAX_STATEMENTS : opts.maxStatements;
+  if (typeof maxStmts === 'number' && Number.isFinite(maxStmts) && statements.length > maxStmts) {
+    throw new Error(
+      `SQL dump too many statements: ${statements.length} exceeds limit of ${maxStmts} ` +
+      `(raise opts.maxStatements or split the dump file)`
+    );
+  }
+
   const created = [];
   let inserted = 0;
   const errors = [];
@@ -221,6 +308,15 @@ async function importDump(engine, sqlText, opts = {}) {
 }
 
 async function importDumpFile(engine, filePath, opts = {}) {
+  // 先看文件大小再决定是否读 —— 避免 fs.readFileSync 把超大 dump 一次性吃进堆
+  const maxLen = opts.maxInputSize == null ? DEFAULT_MAX_SQL_LENGTH : opts.maxInputSize;
+  const stat = fs.statSync(filePath);
+  if (typeof maxLen === 'number' && Number.isFinite(maxLen) && stat.size > maxLen) {
+    throw new Error(
+      `Dump file too large: ${stat.size} bytes exceeds limit of ${maxLen} ` +
+      `(raise opts.maxInputSize or split the file)`
+    );
+  }
   const text = fs.readFileSync(filePath, 'utf8');
   return importDump(engine, text, opts);
 }

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,10 +83,12 @@ function tokenize(sql) {
       while (i < n && sql[i] !== '\n') i++;
       continue;
     }
-    // PG 的 JSON 路径操作符 #> / #>> 尚未实现。
-    // 若不在这里拦截，'#' 会被当成行注释吃掉，导致 SQL 后半段被静默丢弃。
+    // PG 的 JSON 路径操作符 #> / #>>（必须在 '#' 行注释之前识别）
     if (c === '#' && sql[i + 1] === '>') {
-      throw new Error("JSON 路径操作符 '#>' / '#>>' 暂不支持，请改用 '->' / '->>'");
+      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; }
@@ -106,12 +112,15 @@ function tokenize(sql) {
           else str += esc;
           j += 2;
         } else if (sql[j] === quote) {
+          // SQL 标准转义：字符串内两个连续引号表示一个字面量引号（'O''Brien' → O'Brien）
+          if (sql[j + 1] === quote) { str += quote; j += 2; continue; }
           break;
         } else {
           str += sql[j];
           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;
@@ -153,15 +162,17 @@ 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 包含操作符 @> 尚未实现。
-    // 若不拦截，'@' 会被 sysvar 分支静默吞掉、'>' 退化成普通大于号，产生错误结果。
+    // PG 的 JSON 包含操作符 @>
     if (c === '@' && sql[i + 1] === '>') {
-      throw new Error("JSON 包含操作符 '@>' 暂不支持");
+      tokens.push(new SQLToken('op', '@>', i));
+      i += 2;
+      continue;
     }
 
     if (c === '@') {
@@ -181,6 +192,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;
@@ -193,9 +210,11 @@ function tokenize(sql) {
 
     const three = sql.slice(i, i + 3);
     if (sql.slice(i, i + 2) === '<@') {
-      throw new Error("JSON 包含操作符 '<@' 暂不支持");
+      tokens.push(new SQLToken('op', '<@', i));
+      i += 2;
+      continue;
     }
-    if (three === '->>' || three === '<=>') {
+    if (three === '->>' || three === '<=>' || three === '!~*') {
       tokens.push(new SQLToken('op', three, i));
       i += 3;
       continue;
@@ -204,7 +223,7 @@ function tokenize(sql) {
     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;
@@ -1838,6 +1857,13 @@ class Parser {
         this.expect('op', ')');
         return { type: 'cast', expr, dataType };
       }
+      // 零参时间函数：CURRENT_DATE / CURRENT_TIME / CURRENT_TIMESTAMP（可省略括号）。
+      // 此前不在 KEYWORDS 里，被当成列名解析 → "no such column: CURRENT_DATE"
+      if (['CURRENT_DATE', 'CURRENT_TIME', 'CURRENT_TIMESTAMP'].includes(String(t.value).toUpperCase())) {
+        const name = String(t.value).toUpperCase();
+        if (this.peek().type === 'op' && this.peek().value === '(') { this.next(); this.expect('op', ')'); }
+        return { type: 'func', name, args: [] };
+      }
       // EXTRACT(YEAR FROM expr) —— 标准 SQL 的 FROM 形式
       if (String(t.value).toUpperCase() === 'EXTRACT' && this.peek().type === 'op' && this.peek().value === '(') {
         this.next();
@@ -2101,6 +2127,13 @@ class Parser {
         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;
@@ -2202,6 +2235,27 @@ class Parser {
       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 的同义词
     if (t2.type === 'keyword' && (t2.value === 'REGEXP' || t2.value === 'RLIKE')) {
       this.next();
@@ -2209,6 +2263,13 @@ class Parser {
       return { type: 'regexp', operand: left, pattern, not };
     }
 
+    // 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 ...)
@@ -2377,15 +2438,18 @@ function resolveOperand(operand, row, ctx) {
       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;
+      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) {
@@ -2394,6 +2458,17 @@ function resolveOperand(operand, row, ctx) {
       }
       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);
@@ -2425,6 +2500,12 @@ function parseSqlDate(v) {
 
 function pad2(n) { return String(n).padStart(2, '0'); }
 
+/** 本地时区的 'YYYY-MM-DD HH:mm:ss'（MySQL 的 NOW() 语义；区别于 UTC_TIMESTAMP） */
+function sqlLocalDateTime(d = new Date()) {
+  return d.getFullYear() + '-' + pad2(d.getMonth() + 1) + '-' + pad2(d.getDate()) + ' ' +
+    pad2(d.getHours()) + ':' + pad2(d.getMinutes()) + ':' + pad2(d.getSeconds());
+}
+
 /** 按输入形态回写日期：纯日期返回 YYYY-MM-DD，带时间返回 YYYY-MM-DD HH:MM:SS */
 function fmtSqlDate(dateOnly, d) {
   const ymd = d.getFullYear() + '-' + pad2(d.getMonth() + 1) + '-' + pad2(d.getDate());
@@ -2456,9 +2537,11 @@ function applyScalarFunction(fnNode, row, ctx) {
     case 'FOUND_ROWS': return session && session.foundRows !== undefined ? session.foundRows : 0;
     case 'CONNECTION_ID': return session && session.connectionId !== undefined ? session.connectionId : 0;
     case 'DATABASE': case 'SCHEMA': return session && session.currentDb ? session.currentDb : 'default';
-    case 'NOW': case 'CURRENT_TIMESTAMP': return new Date().toISOString().slice(0, 19).replace('T', ' ');
-    case 'CURDATE': case 'CURRENT_DATE': return new Date().toISOString().slice(0, 10);
-    case 'CURTIME': return new Date().toISOString().slice(11, 19);
+    // NOW() / CURDATE() / CURTIME() 返回会话时区（本地）时间，不能用 toISOString()（UTC）——
+    // 否则东八区凌晨会整整差一天（2024-02-29 被存成 2024-02-28）。
+    case 'NOW': case 'CURRENT_TIMESTAMP': return sqlLocalDateTime();
+    case 'CURDATE': case 'CURRENT_DATE': return sqlLocalDateTime().slice(0, 10);
+    case 'CURTIME': return sqlLocalDateTime().slice(11, 19);
     case 'UTC_TIMESTAMP': return new Date().toISOString().slice(0, 19).replace('T', ' ') + ' UTC';
     case 'CONCAT': return args.map(a => a === null || a === undefined ? '' : String(a)).join('');
     case 'CONCAT_WS': {
@@ -2633,6 +2716,57 @@ function likeMatch(value, pattern, ci = true, escape = '\\') {
   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) {
   if (!expr || !schema) return null;
   const filter = {};
@@ -2712,7 +2846,8 @@ function evaluateExpr(expr, row, ctx) {
       const v = resolveOperand(expr.operand, row, ctx);
       if (expr.subquery && expr.subquery._values !== undefined) expr.list = expr.subquery._values;
       if (!expr.list) return false;
-      return expr.list.some(x => x === v || String(x) === String(v));
+      const r = expr.list.some(x => x === v || String(x) === String(v));
+      return expr.not ? !r : r;   // NOT IN：此前漏了取反，导致 NOT IN 与 IN 结果相同
     }
     case 'like': {
       const v = resolveOperand(expr.operand, row, ctx);
@@ -2721,13 +2856,18 @@ function evaluateExpr(expr, row, ctx) {
     }
     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);
@@ -3013,9 +3153,30 @@ 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);
@@ -3028,11 +3189,8 @@ class SQLExecutor {
             : 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]);
-            }
-          }
+          // 唯一列始终参与冲突判定（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)));
@@ -4504,16 +4662,16 @@ class SQLExecutor {
         const rightNulls = (rightRes.schema) ? this._nullPrefixedRow(rightRes.schema, rightPrefix) : null;
         const leftNulls = (rowsAll && rowsAll.schema) ? this._nullPrefixedRow(rowsAll.schema, firstPrefix) : null;
         rows.forEach(l => {
-          let m = null;
+          // 一对多：一个左行可能匹配多个右行，必须全部收进来（此前只取第一个）
+          const hits = [];
           for (let ri = 0; ri < rightRows.length; ri++) {
-            if (evaluateExpr(j.on, { ...l, ...rightRows[ri] })) {
-              m = ri;
-              break;
-            }
+            if (evaluateExpr(j.on, { ...l, ...rightRows[ri] })) hits.push(ri);
           }
-          if (m !== null) {
-            matched.push({ ...l, ...rightRows[m] });
-            unmatchedRight.delete(m);
+          if (hits.length > 0) {
+            for (const ri of hits) {
+              matched.push({ ...l, ...rightRows[ri] });
+              unmatchedRight.delete(ri);
+            }
           } else if (j.type === 'left' || j.type === 'full') {
             matched.push(rightNulls ? { ...rightNulls, ...l } : { ...l });
           }
@@ -4589,6 +4747,10 @@ class SQLExecutor {
       const seen = new Set();
       rows = rows.filter(r => {
         const key = JSON.stringify(statement.columns.map(c => {
+          // SELECT DISTINCT *：按整行去重（此前把 '*' 当列名解析成 null，导致所有行同 key 只剩 1 行）
+          if (c.expr === '*') {
+            return Object.keys(r).filter(k => !String(k).startsWith('_')).sort().map(k => r[k]);
+          }
           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, c.distinct, c.separator, c.orderBy);
@@ -4636,10 +4798,20 @@ class SQLExecutor {
     }
 
     if (statement.orderBy) {
-      // ORDER BY 项可能是列名字符串，也可能是表达式节点
-      const ordVal = (row, o) => (typeof o.column === 'string'
-        ? resolveOperand({ type: 'column', name: o.column }, row, this.ctx)
-        : resolveOperand(o.column, row, this.ctx));
+      // ORDER BY 项可能是列名字符串、表达式节点，或列的位置序号（ORDER BY 1，1-based）
+      const ordNames = statement.columns.map(c => scalarColumnName(c));
+      const ordVal = (row, o) => {
+        const pos = (o.column && typeof o.column === 'object' && o.column.type === 'value' && typeof o.column.value === 'number')
+          ? o.column.value
+          : (typeof o.column === 'number' ? o.column : null);
+        if (pos !== null && pos !== undefined) {
+          const name = ordNames[pos - 1];
+          if (name !== undefined && name !== null) return resolveOperand({ type: 'column', name }, row, this.ctx);
+        }
+        return typeof o.column === 'string'
+          ? resolveOperand({ type: 'column', name: o.column }, row, this.ctx)
+          : resolveOperand(o.column, row, this.ctx);
+      };
       const cmp = (a, b) => {
         for (const o of statement.orderBy) {
           const av = ordVal(a, o);
@@ -4690,53 +4862,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;
 }
 
@@ -4763,7 +4970,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++;
   }
@@ -4812,16 +5019,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++]);
@@ -4854,6 +5079,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 = '';
@@ -4936,14 +5179,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})`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsql-neo",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "JSQL-NEO — Rust-powered embedded database with WASM, REST API, B-Tree indexes, WAL, crash recovery",
   "main": "index.js",
   "types": "index.d.ts",

package/postinstall.js

@@ -14,10 +14,43 @@ const BP = path.join(ROOT, 'bin', BIN_NAME);
 // Native N-API module (native/jsql-neo-native.node)
 const NATIVE_PATH = path.join(ROOT, 'native', 'jsql-neo-native.node');
 
-// GitHub 加速代理前缀；把原始 github 链接直接拼在后面即可
-const GHPROXY = 'https://gh-proxy.com/';
+// GitHub 加速代理前缀；加速站的用法是把原始 URL 直接拼在后面：
+//   https://<host>/https://github.com/owner/repo/releases/download/vX.Y.Z/asset?token=<TOKEN>
+// 可用环境变量覆盖 / 叠加（逗号分隔多个，按序尝试）；空字符串 '' 表示直连兜底。
+// 加速站候选（按优先级）：自建站优先，公共站回退，最后直连兜底。
+const DEFAULT_PROXIES = [
+  'https://gh-proxyjsql-neoworkerapi.vexify.de5.net/',
+  'https://gh-proxy.com/',
+];
+const GHPROXY = process.env.JSQL_GHPROXY !== undefined
+  ? process.env.JSQL_GHPROXY
+  : DEFAULT_PROXIES[0];
+const GHPROXY_TOKEN = process.env.JSQL_GHPROXY_TOKEN || '';
 const TAG = `v${pkg.version}`;
 
+/**
+ * 生成候选下载地址列表（按优先级）：
+ *   环境变量 JSQL_GHPROXY 指定的代理 → 内置加速站 → 直连
+ */
+function proxyCandidates(raw) {
+  const bases = String(process.env.JSQL_GHPROXY || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .concat(DEFAULT_PROXIES)
+    .concat('');
+  const list = [];
+  for (const base of bases) {
+    let url = raw;
+    if (base) url = (base.endsWith('/') ? base : base + '/') + raw;
+    if (base && GHPROXY_TOKEN) {
+      url += (url.indexOf('?') === -1 ? '?' : '&') + 'token=' + encodeURIComponent(GHPROXY_TOKEN);
+    }
+    if (list.indexOf(url) === -1) list.push(url);
+  }
+  return list;
+}
+
 // 从 repository 字段提取 owner/repo，例如 vexify-org/JSQL-neo
 const REPO = (pkg.repository && pkg.repository.url)
   ? pkg.repository.url.replace(/\.git$/, '').replace(/^.*github\.com\//i, '')
@@ -95,20 +128,22 @@ function tryLoadNative() {
 
 async function downloadAndVerify() {
   const asset = `jsql-neo-native.${nativeTargetSuffix()}.node`;
-  const url = `${GHPROXY}https://github.com/${REPO}/releases/download/${TAG}/${asset}`;
-  console.log(`[jsql-neo] downloading native module: ${url}`);
-  try {
-    await download(url, NATIVE_PATH);
-    if (!tryLoadNative()) {
-      console.warn('[jsql-neo] downloaded module also invalid, removed.');
-      return false;
+  const raw = `https://github.com/${REPO}/releases/download/${TAG}/${asset}`;
+  // 依次尝试：环境变量指定的代理 → 内置加速站 → 直连
+  for (const url of proxyCandidates(raw)) {
+    console.log(`[jsql-neo] downloading native module: ${url}`);
+    try {
+      await download(url, NATIVE_PATH);
+      if (tryLoadNative()) {
+        console.log('[jsql-neo] native module downloaded: native/jsql-neo-native.node');
+        return true;
+      }
+      console.warn('[jsql-neo] downloaded module cannot be loaded; trying next source.');
+    } catch (e) {
+      console.warn('[jsql-neo] download failed:', e.message);
     }
-    console.log('[jsql-neo] native module downloaded: native/jsql-neo-native.node');
-    return true;
-  } catch (e) {
-    console.warn('[jsql-neo] download failed, falling back to source build:', e.message);
-    return false;
   }
+  return false;
 }
 
 async function ensureNativeNode() {

package/test/readme-audit.test.js

@@ -142,16 +142,16 @@ async function main() {
   console.log('\n--- 方言特性：DIV / XOR / && / || / <=> / :: / -> ->> / LIKE ESCAPE ---');
   {
     const data = [
-      { id: 1, n: 10, flag: 1, s: '100%', meta: '{"name":"Alice","addr":{"city":"SH"},"tags":["x","y"]}' },
-      { id: 2, n: 20, flag: 0, s: '1000', meta: '{"name":"Bob","addr":{"city":"BJ"},"tags":[]}' },
-      { id: 3, n: 30, flag: 1, s: '100', meta: null },
+      { id: 1, n: 10, flag: 1, s: '100%', nm: 'Alice', meta: '{"name":"Alice","addr":{"city":"SH"},"tags":["x","y"]}' },
+      { id: 2, n: 20, flag: 0, s: '1000', nm: 'Bob', meta: '{"name":"Bob","addr":{"city":"BJ"},"tags":[]}' },
+      { id: 3, n: 30, flag: 1, s: '100', nm: 'Cara', meta: null },
     ];
     const engine = {
       hasTable: () => true, truncate: async () => {}, flush: async () => {},
       find: async () => data.map(r => ({ ...r })),
       getTableSchema: async () => ({
         id: { type: 'integer', primaryKey: true }, n: { type: 'integer' }, flag: { type: 'integer' },
-        s: { type: 'string' }, meta: { type: 'json' },
+        s: { type: 'string' }, nm: { type: 'string' }, meta: { type: 'json' },
       }),
     };
     const rowsOf = async (sql) => {
@@ -176,12 +176,56 @@ async function main() {
       JSON.stringify(await rowsOf("SELECT meta->'addr'->>'city' AS x FROM tbl WHERE id = 1")) === '[["SH"]]');
     ok("->'tags'->>0 数组下标",
       JSON.stringify(await rowsOf("SELECT meta->'tags'->>0 AS x FROM tbl WHERE id = 1")) === '[["x"]]');
+    // PG JSON 包含 / 路径操作符
+    ok("meta @> '{...}' 包含",
+      JSON.stringify(await rowsOf(`SELECT id FROM tbl WHERE meta @> '{"addr":{"city":"SH"}}'`)) === '[[1]]');
+    ok("'{...}' <@ meta 被包含",
+      JSON.stringify(await rowsOf(`SELECT id FROM tbl WHERE '{"name":"Bob"}' <@ meta`)) === '[[2]]');
+    ok("meta#>'{addr,city}' 路径",
+      JSON.stringify(await rowsOf("SELECT meta#>'{addr,city}' AS x FROM tbl WHERE id = 1")) === '[["SH"]]');
+    ok("meta#>>'{addr,city}' 路径文本",
+      JSON.stringify(await rowsOf("SELECT meta#>>'{addr,city}' AS x FROM tbl WHERE id = 1")) === '[["SH"]]');
+    ok("meta#>'{tags,0}' 路径含下标",
+      JSON.stringify(await rowsOf("SELECT meta#>'{tags,0}' AS x FROM tbl WHERE id = 1")) === '[["x"]]');
+    // JSON 键存在 ? / ?| / ?&
+    ok("meta ? 'name'", JSON.stringify(await rowsOf("SELECT id FROM tbl WHERE meta ? 'name'")) === '[[1],[2]]');
+    ok("meta ? 'nope'（不存在）",
+      JSON.stringify(await rowsOf("SELECT id FROM tbl WHERE meta ? 'nope'")) === '[]');
+    ok("meta ?| '{name,nope}'（任一）",
+      JSON.stringify(await rowsOf("SELECT id FROM tbl WHERE meta ?| '{name,nope}'")) === '[[1],[2]]');
+    ok("meta ?& '{name,addr}'（全部）",
+      JSON.stringify(await rowsOf("SELECT id FROM tbl WHERE meta ?& '{name,addr}'")) === '[[1],[2]]');
+    ok("meta ?& '{name,nope}'（缺一个）",
+      JSON.stringify(await rowsOf("SELECT id FROM tbl WHERE meta ?& '{name,nope}'")) === '[]');
+    // PG 正则：~ 敏感 / ~* 不敏感 / !~ 取反
+    ok("nm ~ '^A' 大小写敏感", JSON.stringify(await rowsOf("SELECT id FROM tbl WHERE nm ~ '^A'")) === '[[1]]');
+    ok("nm ~* '^a' 不敏感", JSON.stringify(await rowsOf("SELECT id FROM tbl WHERE nm ~* '^a'")) === '[[1]]');
+    ok("nm !~ '^A' 取反", JSON.stringify(await rowsOf("SELECT id FROM tbl WHERE nm !~ '^A'")) === '[[2],[3]]');
+    ok('REGEXP 仍可用', JSON.stringify(await rowsOf("SELECT id FROM tbl WHERE nm REGEXP '^A'")) === '[[1]]');
+    // —— 6.2.0 回归项（这些曾不报错但结果错）——
+    ok('NOT IN 取反', JSON.stringify(await rowsOf('SELECT id FROM tbl WHERE id NOT IN (1,2)')) === '[[3]]');
+    const dStar = await rowsOf('SELECT DISTINCT * FROM tbl');
+    ok('DISTINCT * 按整行去重（此前只剩 1 行）', dStar.length === 3, dStar);
+    ok('ORDER BY 1 按第 1 列排序', JSON.stringify(await rowsOf('SELECT n FROM tbl ORDER BY 1')) === '[[10],[20],[30]]');
+    ok("'' 内双写引号转义",
+      JSON.stringify(await rowsOf("SELECT 'O''Brien' AS x FROM tbl WHERE id = 1")) === '[["O\'Brien"]]');
     ok("LIKE ... ESCAPE '!' 匹配字面量 %",
       JSON.stringify(await rowsOf("SELECT id FROM tbl WHERE s LIKE '100!%' ESCAPE '!'")) === '[[1]]');
     ok('LIKE 反斜杠转义匹配字面量 %',
       JSON.stringify(await rowsOf("SELECT id FROM tbl WHERE s LIKE '100\\%'")) === '[[1]]');
     ok('LIKE 普通 % 仍为通配',
       JSON.stringify(await rowsOf("SELECT id FROM tbl WHERE s LIKE '100%'")) === '[[1],[2],[3]]');
+
+    // 参数绑定：位置 ? / 命名 :name / 编号 $1（README「Params」一节）
+    const rowsOfP = async (sql, params) => {
+      const r = await executeSQL(engine, sql, params, OPTS);
+      return (Array.isArray(r) ? r[0] : r).rows;
+    };
+    ok('位置参数 ?', JSON.stringify(await rowsOfP('SELECT id FROM tbl WHERE id = ?', [1])) === '[[1]]');
+    ok('命名参数 :id', JSON.stringify(await rowsOfP('SELECT id FROM tbl WHERE id = :id', { id: 2 })) === '[[2]]');
+    ok('命名参数多占位', JSON.stringify(await rowsOfP('SELECT id FROM tbl WHERE id = :a OR id = :b', { a: 1, b: 3 })) === '[[1],[3]]');
+    ok('编号参数 $1', JSON.stringify(await rowsOfP('SELECT id FROM tbl WHERE id = $1', [3])) === '[[3]]');
+    ok('编号参数 $2/$1', JSON.stringify(await rowsOfP('SELECT id FROM tbl WHERE id = $2 OR id = $1', [1, 2])) === '[[1],[2]]');
   }
 
   console.log('\n--- DDL / 解析器节点覆盖 ---');
@@ -325,6 +369,64 @@ async function main() {
     }
   }
 
+  console.log('\n--- 唯一约束：非主键 UNIQUE 必须报 ER_DUP_ENTRY ---');
+  {
+    let JSQL, db;
+    try {
+      ({ JSQL } = require('../lib/native_client.js'));
+      db = new JSQL();
+      await db.start();
+    } catch (e) {
+      console.log('[SKIP] native 不可用：' + e.message.slice(0, 60));
+    }
+    if (db) {
+      const run = (sql) => executeSQL(db, sql, OPTS);
+      const dupErrMsg = async (sql) => {
+        try { await run(sql); return null; } catch (e) { return e.message; }
+      };
+      await run('CREATE TABLE u (id SERIAL PRIMARY KEY, email TEXT UNIQUE, nick TEXT UNIQUE)');
+      await run("INSERT INTO u (email, nick) VALUES ('a@x.com', 'a')");
+      ok('唯一列重复 → ER_DUP_ENTRY',
+        /ER_DUP_ENTRY/.test(await dupErrMsg("INSERT INTO u (email, nick) VALUES ('a@x.com', 'z')") || ''));
+      ok('批内唯一重复 → ER_DUP_ENTRY',
+        /ER_DUP_ENTRY/.test(await dupErrMsg("INSERT INTO u (email, nick) VALUES ('b@x.com', 'n1'), ('c@x.com', 'n1')") || ''));
+      const r1 = await run('SELECT id FROM u');
+      ok('冲突后仍只有 1 行', r1.rows.length === 1, r1.rows);
+      await run("INSERT INTO u (email, nick) VALUES (NULL, 'x'), (NULL, 'y')");
+      const r2 = await run('SELECT id FROM u');
+      ok('UNIQUE 允许多个 NULL', r2.rows.length === 3, r2.rows);
+      await db.stop();
+    }
+  }
+
+  console.log('\n--- 6.2.0 回归：JOIN 一对多 / NOW() 用本地时区 ---');
+  {
+    let JSQL, db;
+    try {
+      ({ JSQL } = require('../lib/native_client.js'));
+      db = new JSQL();
+      await db.start();
+    } catch (e) {
+      console.log('[SKIP] native 不可用：' + e.message.slice(0, 60));
+    }
+    if (db) {
+      const run = (sql) => executeSQL(db, sql, OPTS);
+      await run('CREATE TABLE ru (id INT PRIMARY KEY, name TEXT)');
+      await run('CREATE TABLE ro (id INT PRIMARY KEY, uid INT, amt INT)');
+      await run("INSERT INTO ru (id,name) VALUES (1,'x')");
+      await run('INSERT INTO ro (id,uid,amt) VALUES (1,1,10),(2,1,20),(3,1,30)');
+      const j = await run('SELECT ru.name, ro.amt FROM ru JOIN ro ON ru.id = ro.uid');
+      ok('JOIN 一对多返回 3 行', j.rows.length === 3, j.rows);
+
+      const n = await run('SELECT NOW() AS d');
+      const nowLocal = new Date();
+      const p = (x) => String(x).padStart(2, '0');
+      const expectYmd = nowLocal.getFullYear() + '-' + p(nowLocal.getMonth() + 1) + '-' + p(nowLocal.getDate());
+      ok('NOW() 返回本地时区日期', String(n.rows[0][0]).slice(0, 10) === expectYmd, n.rows);
+      await db.stop();
+    }
+  }
+
   console.log('\n--- Redis：RESP2 帧解析（曾 inline 命令恒为 unknown command）---');
   {
     const { RedisServer } = require('../lib/redis_server.js');