jsql-neo 6.3.3 → 6.3.5

package/lib/database.js

@@ -108,7 +108,10 @@ class Database {
         // WAL（Write-Ahead Logging）
         this._walEnabled = options.wal === true && !this._memoryMode;
         this._walPath = this._filePath ? this._filePath + '.wal' : null;
-        this._walOps = [];          // WAL 操作日志
+        this._walOps = [];          // WAL 操作日志（内存镜像）
+        this._walFlushedCount = 0;  // 已落盘记录数（append-only 增量追加用）
+        this._walReplaying = false; // 回放中：抑制再次写日志
+        this._walReplaySummary = null;
 
         // 事务隔离：默认 REPEATABLE_READ（begin 时保存行快照，rollback 可回滚）
         this._isolationLevel = options.isolationLevel || 'REPEATABLE_READ';
@@ -127,11 +130,21 @@ class Database {
         this._slowQueries = [];
 
         // 从文件加载
-        if (!this._memoryMode && !this._dirMode && fs.existsSync(this._filePath)) {
-            this._loading = true;
-            this._acquireLock();
-            this._load();
-            this._loading = false;
+        // 注意：即使数据文件不存在也要走 _load()，因为可能存在「上次崩溃前
+        // 只写了 WAL、快照尚未落盘」的情况 —— 此时必须回放 WAL 才能恢复数据。
+        // 旧实现在这里用 fs.existsSync 直接短路，导致新建库后崩溃丢数据。
+        if (!this._memoryMode && !this._dirMode) {
+            const hasDataFile = this._filePath ? fs.existsSync(this._filePath) : false;
+            const hasWal = this._walEnabled && this._walPath && fs.existsSync(this._walPath);
+            if (hasDataFile || hasWal) {
+                this._loading = true;
+                if (hasDataFile) this._acquireLock();
+                try {
+                    this._load();
+                } finally {
+                    this._loading = false;
+                }
+            }
         }
 
         // 磁盘/混合模式: 目录存储（每表独立 JSql 文件，增量刷盘）
@@ -365,40 +378,62 @@ class Database {
 
     /**
      * 写入 WAL 日志
+     *
+     * 采用 append-only（每行一条 JSON）而非全量重写：
+     * 全量重写会让日志写入本身成为 O(n²)，且中途崩溃会损坏整个日志文件。
+     * append-only 下崩溃最多丢失最后一行（已 fsync 过的行不会丢）。
      */
     _walWrite(op) {
         if (!this._walEnabled) return;
-        this._walOps.push({
+        const entry = {
             ...op,
             timestamp: Date.now(),
             sequence: this._walOps.length + 1
-        });
+        };
+        this._walOps.push(entry);
+        // 恢复过程中重放操作不能再次写 WAL，否则会无限增长
+        if (this._walReplaying) return;
         this._flushWAL();
     }
 
     /**
-     * 将 WAL 刷入磁盘
+     * 将新增的 WAL 记录追加到磁盘（append-only）
      */
     _flushWAL() {
         if (!this._walEnabled || this._walOps.length === 0) return;
         try {
             const dir = path.dirname(this._walPath);
             if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-            fs.writeFileSync(this._walPath, JSON.stringify(this._walOps), 'utf8');
+            // 只追加尚未落盘的记录
+            const pending = this._walOps.slice(this._walFlushedCount);
+            if (pending.length === 0) return;
+            const lines = pending.map(o => JSON.stringify(o)).join('\n') + '\n';
+            const fd = fs.openSync(this._walPath, 'a');
+            try {
+                fs.writeSync(fd, lines, null, 'utf8');
+                // 崩溃安全性：确保数据真正落到磁盘而不仅在页缓存
+                try { fs.fsyncSync(fd); } catch (e) { /* 某些文件系统不支持 fsync */ }
+            } finally {
+                fs.closeSync(fd);
+            }
+            this._walFlushedCount = this._walOps.length;
         } catch (e) {
             // WAL 写入失败不应阻塞主流程
         }
     }
 
     /**
-     * 检查点：将 WAL 应用到数据文件并清空 WAL
+     * 检查点：数据已由 save() 完整落盘，清空 WAL
+     *
+     * 只在 save() 成功写完快照之后调用。若快照写入失败则不检查点，
+     * 保证 WAL 里的记录仍可用于恢复。
      */
     _checkpoint() {
-        if (!this._walEnabled || this._walOps.length === 0) return;
-        // 所有操作已在内存中生效，此函数仅清除 WAL 文件
+        if (!this._walEnabled) return;
         this._walOps = [];
+        this._walFlushedCount = 0;
         try {
-            if (fs.existsSync(this._walPath)) {
+            if (this._walPath && fs.existsSync(this._walPath)) {
                 fs.unlinkSync(this._walPath);
             }
         } catch (e) {
@@ -407,23 +442,189 @@ class Database {
     }
 
     /**
-     * 崩溃恢复：从 WAL 重放操作
+     * 崩溃恢复：重放 WAL 中尚未被快照覆盖的操作
+     *
+     * 历史问题（6.3.3 及以前）：本函数直接 `fs.unlinkSync` 删除 WAL，
+     * 完全没有回放，导致「WAL / 崩溃恢复」是虚假宣传 —— 实测开启 wal:true
+     * 后 kill -9 丢数据，重开连表都不存在。现在真正回放。
+     *
+     * 日志格式为 append-only JSONL；最后一行可能在崩溃时写半，
+     * 因此解析时逐行 try/catch，坏行直接丢弃（它必然是未完成的那条）。
      */
     _recoverFromWAL() {
         if (!this._walEnabled || !this._walPath || !fs.existsSync(this._walPath)) return;
+
+        let raw;
         try {
-            const walData = JSON.parse(fs.readFileSync(this._walPath, 'utf8'));
-            if (!Array.isArray(walData) || walData.length === 0) return;
-
-            // WAL 操作在 v2.0 中仅用于崩溃恢复标记
-            // 实际操作已在 save() 时持久化，WAL 主要用于：
-            // 1. 标记未完成的事务
-            // 2. 在 save() 间隔中保护数据
-            this._walOps = [];
-            fs.unlinkSync(this._walPath);
+            raw = fs.readFileSync(this._walPath, 'utf8');
         } catch (e) {
-            // WAL 损坏，忽略
-            try { if (fs.existsSync(this._walPath)) fs.unlinkSync(this._walPath); } catch (_) {}
+            return;
+        }
+        if (!raw || !raw.trim()) {
+            this._checkpoint();
+            return;
+        }
+
+        // 兼容 6.3.3 及以前的旧格式：整个 WAL 是一个 JSON 数组（单行）。
+        // 6.3.4 起改为 append-only JSONL（每行一条）。此处按形状识别并归一化，
+        // 否则升级后用户遗留的旧 WAL 会被静默丢弃。
+        let ops = [];
+        const trimmed = raw.trim();
+        if (trimmed.startsWith('[')) {
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (Array.isArray(parsed)) {
+                    ops = parsed.filter(o => o && typeof o.op === 'string');
+                }
+            } catch (e) {
+                // 落到下面的 JSONL 解析
+            }
+        }
+        if (ops.length === 0) {
+            for (const line of raw.split('\n')) {
+                const t = line.trim();
+                if (!t) continue;
+                try {
+                    const o = JSON.parse(t);
+                    if (o && typeof o.op === 'string') ops.push(o);
+                } catch (e) {
+                    // 崩溃时写半的尾行，丢弃
+                }
+            }
+        }
+        if (ops.length === 0) {
+            this._checkpoint();
+            return;
+        }
+
+        this._walReplaying = true;
+        let replayed = 0, failed = 0;
+        try {
+            // 逐条按 sequence 顺序回放，保证 insert→update→remove 的相对次序。
+            // insert 不走 _loadRows()（那是整体替换语义），而是直接 push 到 _rows，
+            // 再在末尾统一重建索引；否则逐条回放会互相覆盖。
+            const touched = new Set();
+            for (const op of ops) {
+                try {
+                    switch (op.op) {
+                        case 'insert': {
+                            const t = op.table && this._tables[op.table];
+                            if (!t || !Array.isArray(op.rows) || op.rows.length === 0) { failed++; break; }
+                            t._rows.push(...op.rows);
+                            touched.add(t);
+                            replayed++;
+                            break;
+                        }
+                        case 'update': {
+                            const t = this._tables[op.table];
+                            if (!t || !op.pk || op.row === undefined) { failed++; break; }
+                            const cur = t._rows.find(r => r[op.pk] === op.id);
+                            if (!cur) { failed++; break; }
+                            Object.assign(cur, op.row);
+                            touched.add(t);
+                            replayed++;
+                            break;
+                        }
+                        case 'remove': {
+                            const t = this._tables[op.table];
+                            if (!t || !op.pk) { failed++; break; }
+                            const before = t._rows.length;
+                            t._rows = t._rows.filter(r => r[op.pk] !== op.id);
+                            if (t._rows.length === before) { failed++; break; }
+                            touched.add(t);
+                            replayed++;
+                            break;
+                        }
+                        default:
+                            if (this._replayWalOp(op)) replayed++;
+                            else failed++;
+                    }
+                } catch (e) {
+                    failed++;
+                }
+            }
+            // 重建受影响表的索引与自增计数
+            for (const t of touched) {
+                if (typeof t._rebuildPKIndex === 'function') t._rebuildPKIndex();
+                if (typeof t._rebuildAllBTrees === 'function') t._rebuildAllBTrees();
+                for (const field of Object.keys(t._indexes || {})) t.createIndex(field);
+                if (t._autoIncrementField) {
+                    for (const row of t._rows) {
+                        const v = row[t._autoIncrementField];
+                        if (typeof v === 'number' && v > t._autoIncrement) t._autoIncrement = v;
+                    }
+                }
+            }
+        } finally {
+            this._walReplaying = false;
+        }
+
+        // 记录回放结果供 getWALInfo() / 排障使用，不打断启动流程
+        if (replayed > 0 || failed > 0) {
+            this._walReplaySummary = { replayed, failed, at: Date.now() };
+        }
+
+        // 回放后的状态已合并进内存。
+        // 必须立即落盘做检查点：否则 WAL 一清空，这批数据就只存在于内存，
+        // 下次崩溃又要「没有快照 + 没有 WAL」而彻底丢失。
+        // 这也是 WAL 的标准语义：recovery 之后必须 checkpoint。
+        if (replayed > 0) {
+            try {
+                this._walCheckpointPending = true;
+                this.save();
+            } catch (e) {
+                // 落盘失败：保留 WAL 以便下次启动重试
+                this._walOps = ops;
+                this._walFlushedCount = 0;
+                this._walCheckpointPending = false;
+                this._walReplaySummary = {
+                    replayed, failed, at: Date.now(),
+                    checkpointFailed: true, error: e.message
+                };
+                return;
+            }
+        }
+
+        // save() 内部已调用 _checkpoint()，此处无需重复。
+    }
+
+    /**
+     * 回放单条 WAL 记录
+     * @returns {boolean} 是否成功应用
+     */
+    _replayWalOp(op) {
+        switch (op.op) {
+            case 'createTable':
+                if (op.table && !this._tables[op.table]) {
+                    this.createTable(op.table, op.schema || {});
+                }
+                return true;
+
+            case 'dropTable':
+                if (op.table && this._tables[op.table]) {
+                    this.dropTable(op.table);
+                }
+                return true;
+
+            case 'insert':
+            case 'update':
+            case 'remove':
+                // 数据类操作由 _recoverFromWAL 按序直接处理（需维护表内行序），
+                // 不走这里。
+                return false;
+
+            // 事务标记：begin/commit/rollback/undo 本身不改数据状态，
+            // 记录它们是为了可观测性；回放时跳过。
+            case 'begin':
+            case 'commit':
+            case 'rollback':
+            case 'undo':
+            case 'restore':
+            case 'import':
+                return true;
+
+            default:
+                return false;
         }
     }
 
@@ -1191,10 +1392,17 @@ class Database {
         if (!this._runHooks('beforeInsert', [tableName, arr])) return [];
         const pk = this._pkOf(table);
         const ids = [];
+        const logged = [];
         for (const row of arr) {
             const r = table.insert(row);
-            ids.push(pk ? r[pk] : table._rows.length);
-        }
+            const id = pk ? r[pk] : table._rows.length;
+            ids.push(id);
+            // 记录落库后的完整行（含自增主键），保证回放能还原真实数据
+            if (pk) logged.push({ ...r });
+            else logged.push(r);
+        }
+        // 有主键才可幂等回放；无主键表回放会重复插行，故不记录
+        if (pk) this._walWrite({ op: 'insert', table: tableName, rows: logged });
         this._emit('insert', { table: tableName, count: arr.length, ids });
         this._runHooks('afterInsert', [tableName, arr, ids]);
         this._markDirty(tableName);
@@ -1291,7 +1499,24 @@ class Database {
         if (!this._runHooks('beforeUpdate', [tableName, id, data])) return;
         const row = this._resolveId(table, id);
         if (!row) return { ok: false, error: 'not found' };
+        // 改主键/唯一列时要先确认新值不与其它行冲突。
+        // 此前直接 Object.assign，导致
+        //   UPDATE t SET id = 1 WHERE id = 2   （t 已有 id=1）
+        // 静默产生两行同主键 —— 主键索引只留一个，SELECT 结果与实际存储不一致。
+        // MySQL / SQLite 都会报 UNIQUE constraint failed。
+        // 注意：UNIQUE 列记录在 table._cachedUniqueFields（不是 _indexes），
+        // 逐行比对即可，未建索引时也能正确拦截。
+        const pk = this._pkOf(table);
+        const uniq = (table._cachedUniqueFields || []).filter(f => f !== pk);
+        for (const field of [pk, ...uniq]) {
+            if (!field || !Object.prototype.hasOwnProperty.call(data, field)) continue;
+            const nv = data[field];
+            if (nv === row[field]) continue;          // 值没变，不算冲突
+            const clash = table._rows.find(r => r !== row && r[field] === nv);
+            if (clash) throw createError('ER_DUP_ENTRY', `Duplicate entry '${nv}' for key '${field}'`);
+        }
         Object.assign(row, data);
+        if (pk) this._walWrite({ op: 'update', table: tableName, pk, id, row: { ...data } });
         this._emit('update', { table: tableName, id, data });
         this._runHooks('afterUpdate', [tableName, id, data, { ok: true }]);
         this._markDirty(tableName);
@@ -1303,10 +1528,15 @@ class Database {
         if (!table) throw createError('ER_NO_SUCH_TABLE', tableName);
         const pairs = entries.map(([id, data]) => [id, data]);
         if (!this._runHooks('beforeUpdate', [tableName, pairs])) return;
+        const pk = this._pkOf(table);
         let count = 0;
         for (const [id, data] of pairs) {
             const row = this._resolveId(table, id);
-            if (row) { Object.assign(row, data); count++; }
+            if (row) {
+                Object.assign(row, data);
+                count++;
+                if (pk) this._walWrite({ op: 'update', table: tableName, pk, id, row: { ...data } });
+            }
         }
         this._emit('update', { table: tableName, entries: pairs, result: { ok: true, count } });
         this._runHooks('afterUpdate', [tableName, pairs, { ok: true, count }]);
@@ -1321,6 +1551,7 @@ class Database {
         if (table._primaryKey) {
             const removed = table.removeById(id);
             if (removed === 0) return { ok: false, error: 'not found' };
+            this._walWrite({ op: 'remove', table: tableName, pk: table._primaryKey, id });
             this._emit('delete', { table: tableName, id });
             this._runHooks('afterDelete', [tableName, id, { ok: true }]);
             this._markDirty(tableName);
@@ -1346,13 +1577,21 @@ class Database {
         if (table._primaryKey) {
             for (const id of ids) removed += table.removeById(id);
         } else {
+            // 无主键表没有稳定的行标识，_resolveId 只能把 id 当 1-based 行号，
+            // 而 _rowPkId 在无主键时回退到 row.id（业务列名）——
+            // 两者语义不一致，导致 DELETE ... WHERE id IN (3,5) 删错行。
+            // 这里先按「行对象 === id」尝试（SQL 层可以直接传行引用），
+            // 退化到行号解析；并一次性收集目标后统一移除，避免边删边移位。
+            const targets = [];
+            const seen = new Set();
+            const push = (row) => { if (row && !seen.has(row)) { seen.add(row); targets.push(row); } };
             for (const id of ids) {
-                const row = this._resolveId(table, id);
-                const idx = row ? table._rows.findIndex(r => r === row) : -1;
-                if (idx !== -1) {
-                    table._rows.splice(idx, 1);
-                    removed++;
-                }
+                if (id && typeof id === 'object') { push(id); continue; }
+                push(this._resolveId(table, id));
+            }
+            if (targets.length) {
+                table._rows = table._rows.filter(r => !seen.has(r));
+                removed = targets.length;
             }
             table._rebuildPKIndex();
             table._rebuildAllBTrees();
@@ -1590,6 +1829,8 @@ class Database {
                     this._tables[name]._loadRows(rows);
                 }
             }
+            // WAL 恢复（此前 .jsql 分支提前 return，导致崩溃后数据全丢）
+            this._recoverFromWAL();
             return;
         }
 

package/lib/native_client.js

@@ -264,12 +264,38 @@ class JSQL {
     // native 引擎：钩子内再次调用引擎方法会触发 N-API 重入崩溃，需显式防护
     this._forbidReentry = true;
     this._eventListeners = [];
+
+    // 每个 Database 实例分配独立的 native 引擎句柄。
+    // 旧版 native 层是进程级单例，导致 new Database(dirA) 后再 new Database(dirB)
+    // 会把 dirA 的表全部清空（见 HybridEngine::open 的 clear()）。
+    // 6.3.4 起 native 层改为句柄注册表，同进程可并存多个独立数据库。
+    // 若加载到的是旧版预编译二进制（无 jsqlInstanceNew），则回退到单实例行为。
+    this._handle = null;
+    this._multiInstance = typeof native.jsqlInstanceNew === 'function';
+    if (this._multiInstance) {
+      this._handle = native.jsqlInstanceNew();
+    }
     if (this._autoPlugins) {
       const { ModuleManager } = require('./mod');
       new ModuleManager().applyTo(this);
     }
   }
 
+  /**
+   * 调用 native 引擎，自动带上本实例的句柄。
+   *
+   * 句柄版函数名 = 原名 + 'H'（jsqlFind -> jsqlFindH）。
+   * 加载到旧版二进制（无句柄 API）时自动回退到无句柄调用，
+   * 保证新版本 JS 能配旧二进制、不会因缺少导出而崩。
+   */
+  _n(name, ...args) {
+    if (this._multiInstance && this._handle !== null) {
+      const fn = native[name + 'H'];
+      if (typeof fn === 'function') return fn(this._handle, ...args);
+    }
+    return native[name](...args);
+  }
+
   use(plugin, opts) {
     return applyPlugin(this, plugin, opts);
   }
@@ -318,7 +344,7 @@ class JSQL {
       if (!this._path) throw new Error('hybrid/disk mode requires a directory path');
       let r;
       try {
-        r = safeParse(native.jsqlOpen(this._path, this._mode));
+        r = safeParse(this._n('jsqlOpen', this._path, this._mode));
       } catch (e) {
         throw new Error('failed to open native storage: ' + e.message);
       }
@@ -329,7 +355,7 @@ class JSQL {
       }
     } else {
       try {
-        JSON.parse(native.jsqlOpen('', 'memory'));
+        JSON.parse(this._n('jsqlOpen', '', 'memory'));
       } catch (e) {
         throw new Error('failed to open native memory storage: ' + e.message);
       }
@@ -337,7 +363,7 @@ class JSQL {
     if (this._mode !== 'memory') {
       if (this._flushInterval > 0) {
         this._diskFlushTimer = setInterval(() => {
-          try { native.jsqlFlushDirty(); } catch (e) { /* ignore */ }
+          try { this._n('jsqlFlushDirty'); } catch (e) { /* ignore */ }
         }, this._flushInterval);
         if (this._diskFlushTimer.unref) this._diskFlushTimer.unref();
       }
@@ -358,7 +384,7 @@ class JSQL {
     if (process.memoryUsage().rss <= budget) return;
     for (let i = 0; i < 16; i++) {
       let r;
-      try { r = JSON.parse(native.jsqlEvict()); } catch (e) { return; }
+      try { r = JSON.parse(this._n('jsqlEvict')); } catch (e) { return; }
       if (r.ok === false || !r.evicted || r.remaining === 0) return;
       if (process.memoryUsage().rss <= budget) return;
     }
@@ -401,11 +427,11 @@ class JSQL {
     if (pk) {
       const filter = {};
       filter[pk] = this._coercePkId(table, id);
-      const r = safeParse(native.jsqlFind(table, JSON.stringify(filter), 1, 0));
+      const r = safeParse(this._n('jsqlFind', table, JSON.stringify(filter), 1, 0));
       if (r && r.error) return r;
       return Array.isArray(r) && r.length > 0 ? r[0] : null;
     }
-    return safeParse(native.jsqlFindById(table, Number(id)));
+    return safeParse(this._n('jsqlFindById', table, Number(id)));
   }
 
   _seqIdByPk(table, id) {
@@ -413,7 +439,7 @@ class JSQL {
     if (pk) {
       const filter = {};
       filter[pk] = this._coercePkId(table, id);
-      const r = safeParse(native.jsqlFind(table, JSON.stringify(filter), 1, 0));
+      const r = safeParse(this._n('jsqlFind', table, JSON.stringify(filter), 1, 0));
       if (Array.isArray(r) && r.length > 0) return r[0].id;
       return null;
     }
@@ -442,7 +468,7 @@ class JSQL {
       });
     }
     const bin = encodeBatch(rows);
-    const r = safeParse(native.jsqlInsertBuf(table, bin));
+    const r = safeParse(this._n('jsqlInsertBuf', table, bin));
     if (r && r.error) throw new Error(r.error);
     if (r && Array.isArray(r) && !this._pkAutoIncrement(table)) {
       const pk = this._pkOf(table);
@@ -471,13 +497,13 @@ class JSQL {
       var ids = remove[table];
       if (ids.size === 0) continue;
       var idsArr = Array.from(ids);
-      var r = safeParse(native.jsqlRemoveByIds(table, JSON.stringify(idsArr)));
+      var r = safeParse(this._n('jsqlRemoveByIds', table, JSON.stringify(idsArr)));
       this._emit('delete', { table, ids: idsArr, result: r });
     }
     for (var table in update) {
       var entries = update[table];
       if (entries.length === 0) continue;
-      var r = safeParse(native.jsqlUpdateByIds(table, JSON.stringify(entries)));
+      var r = safeParse(this._n('jsqlUpdateByIds', table, JSON.stringify(entries)));
       this._emit('update', { table, entries, result: r });
     }
     this._opBuffer = { remove: {}, update: {} };
@@ -531,7 +557,7 @@ class JSQL {
     await this._flush();
     this._flushOpsNow();
     if (this._mode !== 'memory') {
-      try { native.jsqlFlushDirty(); } catch (e) { /* ignore */ }
+      try { this._n('jsqlFlushDirty'); } catch (e) { /* ignore */ }
     }
   }
 
@@ -570,7 +596,7 @@ class JSQL {
     await this._flush();
     if (typeof schema === 'string') schema = parseSchemaString(schema);
     if (!this._runHooks('beforeCreateTable', [name, schema])) return null;
-    const r = safeParse(native.jsqlCreateTable(name, JSON.stringify(mapNativeSchema(schema))));
+    const r = safeParse(this._n('jsqlCreateTable', name, JSON.stringify(mapNativeSchema(schema))));
     if (r && r.ok === false) throw new Error(r.error || 'create table failed');
     this._tableNames.add(name);
     this._schemas[name] = typeof schema === 'string' ? mapNativeSchema(schema) : schema;
@@ -582,7 +608,7 @@ class JSQL {
   async addColumn(table, name, def) {
     await this._flush();
     const mapped = mapNativeSchema({ [name]: def })[name];
-    const r = safeParse(native.jsqlAddColumn(table, name, JSON.stringify(mapped)));
+    const r = safeParse(this._n('jsqlAddColumn', table, name, JSON.stringify(mapped)));
     if (r && r.ok === false) throw new Error(r.error || 'add column failed');
     if (!this._schemas[table]) this._schemas[table] = {};
     this._schemas[table][name] = mapped;
@@ -593,7 +619,7 @@ class JSQL {
   async dropTable(name) {
     await this._flush();
     if (!this._runHooks('beforeDropTable', [name])) return null;
-    const r = safeParse(native.jsqlDropTable(name));
+    const r = safeParse(this._n('jsqlDropTable', name));
     if (r && r.ok === false) throw new Error(r.error || 'drop table failed');
     this._tableNames.delete(name);
     delete this._schemas[name];
@@ -620,7 +646,7 @@ class JSQL {
     if (this._pkOf(table)) {
       r = ids.map(id => this._findRawById(table, id)).filter(x => x !== null && !(x && x.error));
     } else {
-      r = safeParse(native.jsqlFindByIds(table, JSON.stringify(ids)));
+      r = safeParse(this._n('jsqlFindByIds', table, JSON.stringify(ids)));
     }
     if (r && r.error) throw new Error(r.error);
     this._runHooks('afterFind', [table, { ids }, r]);
@@ -638,7 +664,7 @@ class JSQL {
     if (!this._runHooks('beforeFind', [table, { filter, opts }])) return [];
     const filterStr = filter ? JSON.stringify(filter) : '';
     const { limit = 100, offset = 0 } = opts;
-    const r = safeParse(native.jsqlFind(table, filterStr, limit, offset));
+    const r = safeParse(this._n('jsqlFind', table, filterStr, limit, offset));
     if (r && r.error) throw new Error(r.error);
     this._runHooks('afterFind', [table, { filter, opts }, r]);
     const schema = this._schemas[table];
@@ -649,7 +675,7 @@ class JSQL {
   async count(table) {
     this._flushOpsNow();
     this._runHooks('beforeCount', [table]);
-    const r = parseInt(native.jsqlCount(table), 10);
+    const r = parseInt(this._n('jsqlCount', table), 10);
     const n = isNaN(r) ? 0 : r;
     this._runHooks('afterCount', [table, n]);
     return n;
@@ -736,7 +762,17 @@ class JSQL {
     if (this._diskFlushTimer) { clearInterval(this._diskFlushTimer); this._diskFlushTimer = null; }
     if (this._evictTimer) { clearInterval(this._evictTimer); this._evictTimer = null; }
     if (this._mode !== 'memory') {
-      try { JSON.parse(native.jsqlClose()); } catch (e) { /* ignore */ }
+      try { JSON.parse(this._n('jsqlClose')); } catch (e) { /* ignore */ }
+    }
+    // 释放本实例的引擎句柄，避免 native 侧内存泄漏
+    // （多实例下不释放会一直占用，直到进程退出）
+    if (this._handle !== null) {
+      try {
+        if (typeof native.jsqlInstanceFree === 'function') {
+          JSON.parse(native.jsqlInstanceFree(this._handle));
+        }
+      } catch (e) { /* ignore */ }
+      this._handle = null;
     }
     this._runHooks('onStop', []);
     this._emit('stop', {});
@@ -744,7 +780,7 @@ class JSQL {
 
   async beginTx() {
     this._flushOpsNow();
-    const r = safeParse(native.jsqlBeginTx());
+    const r = safeParse(this._n('jsqlBeginTx'));
     if (r && r.ok === false) throw new Error(r.error || 'begin transaction failed');
     this._txId = r.txId;
     return r.txId;
@@ -769,13 +805,13 @@ class JSQL {
   }
 
   async commitTx(txId) {
-    const r = safeParse(native.jsqlCommitTx(String(txId)));
+    const r = safeParse(this._n('jsqlCommitTx', String(txId)));
     if (r && r.ok === false) throw new Error(r.error || 'commit transaction failed');
     return true;
   }
 
   async rollbackTx(txId) {
-    const r = safeParse(native.jsqlRollbackTx(String(txId)));
+    const r = safeParse(this._n('jsqlRollbackTx', String(txId)));
     if (r && r.ok === false) throw new Error(r.error || 'rollback transaction failed');
     return true;
   }