@h-ai/reldb 0.1.0-alpha.49 → 0.1.0-alpha.51

package/README.md

@@ -74,6 +74,24 @@ await reldb.init({
 })
 ```
 
+### SQLite 执行方式（worker 异步）
+
+better-sqlite3 是同步驱动，查询会阻塞 Node 主线程事件循环。WAL 只能改善数据库锁并发，无法避免同步调用占用主线程。需要卸载这一阻塞时，可把 SQLite 切到专用 worker 线程执行（单连接，opt-in，默认 `sync`）：
+
+```ts
+await reldb.init({
+  type: 'sqlite',
+  database: './data.db',
+  sqlite: {
+    executor: 'worker', // 'sync'（默认）| 'worker'
+    walMode: true, // 默认 true
+    workerConnectTimeoutMs: 10000, // worker 打开连接超时，默认 10000
+  },
+})
+```
+
+worker 模式下查询、写入与事务均在 worker 线程串行执行；公共 API 与返回值与同步模式完全一致。
+
 ### 操作日志
 
 可在数据库配置中通过 `operationLog` 开启 SQL 操作日志。日志在 reldb provider-base 的 DML 操作层统一输出，不在 `reldb-main.ts` 或各 raw provider 中重复包装。

package/dist/index.d.ts

@@ -93,14 +93,20 @@ type SslConfig = z.infer<typeof SslConfigSchema>;
  * @example
  * ```ts
  * sqlite: {
- *     walMode: true,   // 启用 WAL 模式，提高并发性能
- *     readonly: false  // 只读模式
+ *     walMode: true,        // 启用 WAL 模式，提高并发性能
+ *     readonly: false,      // 只读模式
+ *     executor: 'worker'    // 用 worker 线程执行，避免同步查询阻塞主线程事件循环
  * }
  * ```
  */
 declare const SqliteOptionsSchema: z.ZodObject<{
     walMode: z.ZodDefault<z.ZodBoolean>;
     readonly: z.ZodDefault<z.ZodBoolean>;
+    executor: z.ZodDefault<z.ZodEnum<{
+        sync: "sync";
+        worker: "worker";
+    }>>;
+    workerConnectTimeoutMs: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 /**
  * MySQL 特定选项 Schema
@@ -145,6 +151,11 @@ declare const SqliteConfigSchema: z.ZodObject<{
     sqlite: z.ZodOptional<z.ZodObject<{
         walMode: z.ZodDefault<z.ZodBoolean>;
         readonly: z.ZodDefault<z.ZodBoolean>;
+        executor: z.ZodDefault<z.ZodEnum<{
+            sync: "sync";
+            worker: "worker";
+        }>>;
+        workerConnectTimeoutMs: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /**
@@ -274,6 +285,11 @@ declare const ReldbConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     sqlite: z.ZodOptional<z.ZodObject<{
         walMode: z.ZodDefault<z.ZodBoolean>;
         readonly: z.ZodDefault<z.ZodBoolean>;
+        executor: z.ZodDefault<z.ZodEnum<{
+            sync: "sync";
+            worker: "worker";
+        }>>;
+        workerConnectTimeoutMs: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     url: z.ZodOptional<z.ZodString>;

package/dist/index.js

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 import { core, ok, err } from '@h-ai/core';
+import { existsSync } from 'fs';
 import { createRequire } from 'module';
+import { Worker } from 'worker_threads';
 
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
   get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
@@ -37,7 +39,17 @@ var SqliteOptionsSchema = z.object({
   /** 是否启用 WAL 模式（默认 true），可提高并发读写性能 */
   walMode: z.boolean().default(true),
   /** 是否只读模式（默认 false） */
-  readonly: z.boolean().default(false)
+  readonly: z.boolean().default(false),
+  /**
+   * 执行方式（默认 sync）。
+   *
+   * - `sync`：主线程直接执行 better-sqlite3（同步阻塞主线程事件循环）。
+   * - `worker`：在专用 worker 线程持有唯一连接执行，把阻塞移出主线程。
+   *   注意 WAL 只改善数据库锁并发，无法避免 better-sqlite3 同步调用占用调用线程。
+   */
+  executor: z.enum(["sync", "worker"]).default("sync"),
+  /** worker 执行方式下等待连接打开的超时（毫秒，默认 10000） */
+  workerConnectTimeoutMs: z.number().int().positive().default(1e4)
 });
 var MysqlOptionsSchema = z.object({
   /** 字符集（默认 utf8mb4），推荐使用 utf8mb4 支持完整 Unicode */
@@ -2320,9 +2332,157 @@ function createPostgresProvider() {
   };
 }
 var require2 = createRequire(import.meta.url);
+function createSyncSqliteEngine(options) {
+  const Database = require2("better-sqlite3");
+  const db = new Database(options.database, { readonly: options.readonly });
+  if (options.walMode !== false) {
+    db.pragma("journal_mode = WAL");
+  }
+  let open = true;
+  return {
+    async all(sql, params) {
+      const stmt = db.prepare(sql);
+      return params ? stmt.all(...params) : stmt.all();
+    },
+    async get(sql, params) {
+      const stmt = db.prepare(sql);
+      return (params ? stmt.get(...params) : stmt.get()) ?? null;
+    },
+    async run(sql, params) {
+      const stmt = db.prepare(sql);
+      const result = params ? stmt.run(...params) : stmt.run();
+      return { changes: result.changes, lastInsertRowid: result.lastInsertRowid };
+    },
+    async exec(sql) {
+      db.exec(sql);
+    },
+    async batch(statements) {
+      const tx = db.transaction((items) => {
+        for (const item of items) {
+          const stmt = db.prepare(item.sql);
+          if (item.params)
+            stmt.run(...item.params);
+          else stmt.run();
+        }
+      });
+      tx(statements);
+    },
+    async close() {
+      if (open) {
+        db.close();
+        open = false;
+      }
+    },
+    isOpen: () => open
+  };
+}
+function resolveWorkerUrl() {
+  const candidates = [
+    // 源码 / 测试：引擎与 worker 同目录。
+    new URL("./reldb-sqlite-worker.mjs", import.meta.url),
+    // 打包：引擎被并入 dist/index.js，worker 复制到 dist/providers/sqlite/。
+    new URL("./providers/sqlite/reldb-sqlite-worker.mjs", import.meta.url)
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate))
+      return candidate;
+  }
+  return candidates[0];
+}
+async function createWorkerSqliteEngine(options, connectTimeoutMs) {
+  const worker = new Worker(resolveWorkerUrl(), {
+    workerData: { database: options.database, readonly: options.readonly, walMode: options.walMode }
+  });
+  let seq = 0;
+  let open = true;
+  const pending = /* @__PURE__ */ new Map();
+  function rejectAll(error) {
+    for (const entry of pending.values())
+      entry.reject(error);
+    pending.clear();
+  }
+  worker.on("message", (msg) => {
+    if (!("id" in msg))
+      return;
+    const entry = pending.get(msg.id);
+    if (!entry)
+      return;
+    pending.delete(msg.id);
+    if (msg.ok)
+      entry.resolve(msg.result);
+    else entry.reject(new Error(msg.error?.message ?? "sqlite worker error"));
+  });
+  worker.on("error", (error) => {
+    open = false;
+    rejectAll(error instanceof Error ? error : new Error(String(error)));
+  });
+  worker.on("exit", (code) => {
+    open = false;
+    if (pending.size > 0)
+      rejectAll(new Error(`sqlite worker exited unexpectedly with code ${code}`));
+  });
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      worker.off("message", onHandshake);
+      reject(new Error(`sqlite worker init timed out after ${connectTimeoutMs}ms`));
+    }, connectTimeoutMs);
+    function onHandshake(msg) {
+      if (msg?.type === "ready") {
+        clearTimeout(timer);
+        worker.off("message", onHandshake);
+        resolve();
+      } else if (msg?.type === "init-error") {
+        clearTimeout(timer);
+        worker.off("message", onHandshake);
+        reject(new Error(msg.error?.message ?? "sqlite worker init failed"));
+      }
+    }
+    worker.on("message", onHandshake);
+  });
+  function post(op, payload) {
+    if (!open)
+      return Promise.reject(new Error("sqlite worker is not open"));
+    const id = ++seq;
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject });
+      worker.postMessage({ id, op, ...payload });
+    });
+  }
+  return {
+    // 边界反序列化：worker 通过结构化克隆回传，行/结果类型在此断言。
+    async all(sql, params) {
+      return await post("all", { sql, params });
+    },
+    async get(sql, params) {
+      return await post("get", { sql, params });
+    },
+    async run(sql, params) {
+      return await post("run", { sql, params });
+    },
+    async exec(sql) {
+      await post("exec", { sql });
+    },
+    async batch(statements) {
+      await post("batch", { statements });
+    },
+    async close() {
+      if (!open)
+        return;
+      try {
+        await post("close", {});
+      } catch {
+      }
+      open = false;
+      await worker.terminate();
+    },
+    isOpen: () => open
+  };
+}
+
+// src/providers/reldb-provider-sqlite.ts
 var logger4 = core.logger.child({ module: "reldb", scope: "sqlite" });
 function createSqliteProvider() {
-  let database = null;
+  let engine = null;
   let currentConfig2 = null;
   let txChain = Promise.resolve();
   const TX_LOCK_TIMEOUT_MS = 3e4;
@@ -2350,7 +2510,7 @@ function createSqliteProvider() {
     return release;
   }
   const ctx = {
-    isConnected: () => database !== null && database.open,
+    isConnected: () => engine !== null && engine.isOpen(),
     logger: logger4,
     operationLog: () => currentConfig2?.operationLog
   };
@@ -2393,71 +2553,59 @@ function createSqliteProvider() {
     async createTable(name, columns, ifNotExists = true) {
       const quotedTable = quoteIdentifier(name);
       const sql = buildDefaultCreateTableSql(sqliteBuildColumnSql, quotedTable, columns, ifNotExists);
-      database.exec(sql);
+      await engine.exec(sql);
       return ok(void 0);
     },
     async dropTable(name, ifExists) {
       const ifExistsClause = ifExists ? "IF EXISTS " : "";
-      database.exec(`DROP TABLE ${ifExistsClause}${quoteIdentifier(name)}`);
+      await engine.exec(`DROP TABLE ${ifExistsClause}${quoteIdentifier(name)}`);
       return ok(void 0);
     },
     async addColumn(table, column, def) {
       const colSql = sqliteBuildColumnSql(column, def);
-      database.exec(`ALTER TABLE ${quoteIdentifier(table)} ADD COLUMN ${colSql}`);
+      await engine.exec(`ALTER TABLE ${quoteIdentifier(table)} ADD COLUMN ${colSql}`);
       return ok(void 0);
     },
     async dropColumn(table, column) {
-      database.exec(`ALTER TABLE ${quoteIdentifier(table)} DROP COLUMN ${quoteIdentifier(column)}`);
+      await engine.exec(`ALTER TABLE ${quoteIdentifier(table)} DROP COLUMN ${quoteIdentifier(column)}`);
       return ok(void 0);
     },
     async renameTable(oldName, newName) {
-      database.exec(buildDefaultRenameTableSql(quoteIdentifier(oldName), quoteIdentifier(newName)));
+      await engine.exec(buildDefaultRenameTableSql(quoteIdentifier(oldName), quoteIdentifier(newName)));
       return ok(void 0);
     },
     async createIndex(table, index, def) {
       const sql = buildDefaultCreateIndexSql(quoteIdentifier, quoteIdentifier(table), quoteIdentifier(index), def);
-      database.exec(sql);
+      await engine.exec(sql);
       return ok(void 0);
     },
     async dropIndex(index, ifExists = true) {
       const sql = buildDefaultDropIndexSql(quoteIdentifier, index, ifExists);
-      database.exec(sql);
+      await engine.exec(sql);
       return ok(void 0);
     },
     async raw(sql) {
-      database.exec(sql);
+      await engine.exec(sql);
       return ok(void 0);
     }
   };
   const rawDml = {
     async query(sql, params) {
-      const stmt = database.prepare(sql);
-      const rows = params ? stmt.all(...params) : stmt.all();
+      const rows = await engine.all(sql, params);
       return ok(rows);
     },
     async get(sql, params) {
-      const stmt = database.prepare(sql);
-      const row = params ? stmt.get(...params) : stmt.get();
+      const row = await engine.get(sql, params);
       return ok(row ?? null);
     },
     async execute(sql, params) {
-      const stmt = database.prepare(sql);
-      const result = params ? stmt.run(...params) : stmt.run();
-      return ok({ changes: result.changes, lastInsertRowid: result.lastInsertRowid });
+      const result = await engine.run(sql, params);
+      return ok(result);
     },
     async batch(statements) {
       const releaseTxLock = await acquireTxLock();
       try {
-        const db = database;
-        const transaction = db.transaction(() => {
-          for (const { sql: s, params } of statements) {
-            const stmt = db.prepare(s);
-            if (params)
-              stmt.run(...params);
-            else stmt.run();
-          }
-        });
-        transaction();
+        await engine.batch(statements);
         return ok(void 0);
       } catch (error) {
         return err(HaiReldbError.QUERY_FAILED, reldbM("reldb_sqliteBatchFailed", { params: { error: String(error) } }), error);
@@ -2467,45 +2615,32 @@ function createSqliteProvider() {
     },
     async queryPage(options) {
       const result = await queryPageAsync(
-        async (sqlStr, params) => {
-          const stmt = database.prepare(sqlStr);
-          return params ? stmt.all(...params) : stmt.all();
-        },
+        (sqlStr, params) => engine.all(sqlStr, params),
         options
       );
       return ok(result);
     }
   };
-  function createSqliteTxDmlOps(db) {
+  function createSqliteTxDmlOps(txEngine) {
     return {
       async query(sql, params) {
-        const stmt = db.prepare(sql);
-        return ok(params ? stmt.all(...params) : stmt.all());
+        return ok(await txEngine.all(sql, params));
       },
       async get(sql, params) {
-        const stmt = db.prepare(sql);
-        return ok((params ? stmt.get(...params) : stmt.get()) ?? null);
+        return ok(await txEngine.get(sql, params) ?? null);
       },
       async execute(sql, params) {
-        const stmt = db.prepare(sql);
-        const result = params ? stmt.run(...params) : stmt.run();
-        return ok({ changes: result.changes, lastInsertRowid: result.lastInsertRowid });
+        return ok(await txEngine.run(sql, params));
       },
       async batch(statements) {
         for (const { sql: s, params } of statements) {
-          const stmt = db.prepare(s);
-          if (params)
-            stmt.run(...params);
-          else stmt.run();
+          await txEngine.run(s, params);
         }
         return ok(void 0);
       },
       async queryPage(options) {
         const result = await queryPageAsync(
-          async (sqlStr, params) => {
-            const stmt = db.prepare(sqlStr);
-            return params ? stmt.all(...params) : stmt.all();
-          },
+          (sqlStr, params) => txEngine.all(sqlStr, params),
           options
         );
         return ok(result);
@@ -2513,7 +2648,7 @@ function createSqliteProvider() {
     };
   }
   async function beginTx() {
-    const db = database;
+    const txEngine = engine;
     let released = false;
     const releaseTxLock = await acquireTxLock();
     const finishTransaction = () => {
@@ -2523,19 +2658,19 @@ function createSqliteProvider() {
       }
     };
     try {
-      db.exec("BEGIN TRANSACTION");
+      await txEngine.exec("BEGIN TRANSACTION");
     } catch (error) {
       finishTransaction();
       return err(HaiReldbError.TRANSACTION_FAILED, sqliteTxErrorMessage(String(error)), error);
     }
-    const txDmlOps = createSqliteTxDmlOps(db);
+    const txDmlOps = createSqliteTxDmlOps(txEngine);
     const guardedTxDmlOps = createBaseDmlOps(ctx, txDmlOps);
     return ok(createTxHandle(guardedTxDmlOps, {
       commit: async () => {
-        db.exec("COMMIT");
+        await txEngine.exec("COMMIT");
       },
       rollback: async () => {
-        db.exec("ROLLBACK");
+        await txEngine.exec("ROLLBACK");
       },
       release: () => finishTransaction(),
       errorMessage: sqliteTxErrorMessage
@@ -2551,40 +2686,41 @@ function createSqliteProvider() {
         return err(HaiReldbError.CONFIG_ERROR, reldbM("reldb_sqliteNeedPath"));
       }
       try {
-        const Database = require2("better-sqlite3");
         const sqliteOptions = {
           walMode: true,
           readonly: false,
+          executor: "sync",
+          workerConnectTimeoutMs: 1e4,
           ...config.sqlite ?? {}
         };
-        database = new Database(config.database, {
-          readonly: sqliteOptions.readonly ?? false
-        });
-        if (sqliteOptions.walMode !== false) {
-          database.pragma("journal_mode = WAL");
-        }
+        const engineOptions = {
+          database: config.database,
+          readonly: sqliteOptions.readonly ?? false,
+          walMode: sqliteOptions.walMode !== false
+        };
+        engine = sqliteOptions.executor === "worker" ? await createWorkerSqliteEngine(engineOptions, sqliteOptions.workerConnectTimeoutMs ?? 1e4) : createSyncSqliteEngine(engineOptions);
         currentConfig2 = config;
-        logger4.info("Connected to SQLite", { database: config.database });
+        logger4.info("Connected to SQLite", { database: config.database, executor: sqliteOptions.executor });
         return ok(void 0);
       } catch (error) {
         return err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_sqliteConnectionFailed", { params: { error: String(error) } }), error);
       }
     },
     async close() {
-      if (database) {
+      if (engine) {
         try {
           try {
             await txChain;
           } catch {
           }
-          database.close();
+          await engine.close();
         } catch (error) {
           currentConfig2 = null;
-          database = null;
+          engine = null;
           return err(HaiReldbError.CONNECTION_FAILED, reldbM("reldb_sqliteConnectionFailed", { params: { error: String(error) } }), error);
         }
         currentConfig2 = null;
-        database = null;
+        engine = null;
         logger4.info("Disconnected from SQLite");
       }
       return ok(void 0);