🔍 登录 注册

Node.js 内置 SQLite:node:sqlite 的工程化用法与边界

云 云边小卖部 2026-11-17 👁 1 ⏱ 5min

Node.js 内置 SQLite:node:sqlite 的工程化用法与边界

Node 22 引入的实验性 node:sqlite 到 Node 24/26 已逐步稳定,官方文档甚至专门补了"如何绑定数字与 BigInt"这类细节。对桌面工具、边缘节点、本地缓存、嵌入式规则引擎这些场景,零依赖的进程内数据库价值很大:没有 sidecar、没有端口、没有连接池。本文按工程视角梳理它的正确用法与明确的边界。

一、最小可用形态

import { DatabaseSync } from "node:sqlite";

const db = new DatabaseSync("/var/lib/okgoes/local-cache.db");
db.exec("PRAGMA journal_mode = WAL;");
db.exec(`CREATE TABLE IF NOT EXISTS kv (
  k TEXT PRIMARY KEY, v TEXT NOT NULL, exp_at INTEGER
)`);

const insert = db.prepare(
  "INSERT INTO kv(k, v, exp_at) VALUES (?, ?, ?) ON CONFLICT(k) DO UPDATE SET v=excluded.v, exp_at=excluded.exp_at"
);
insert.run("hot:articles", JSON.stringify(list), Date.now() + 60_000);

const row = db.prepare("SELECT v FROM kv WHERE k = ? AND (exp_at IS NULL OR exp_at > ?)")
               .get("hot:articles", Date.now());

要点:DatabaseSync 是同步 API——这是设计决策而非偷懒,它面向的是"数据量小、操作短"的嵌入式场景。所有语句用 prepare 复用,参数走绑定而不是字符串拼接。

二、BigInt 与数值类型绑定

SQLite 的 INTEGER 是 64 位,JS number 只有 53 位安全整数。node:sqlite 的默认行为是:能安全表示为 number 的就返回 number,超出范围返回 BigInt;写入时两者都接受,但浮点写进 INTEGER 列会按 SQLite 规则截断。

db.exec("CREATE TABLE logs(id INTEGER PRIMARY KEY, bytes INTEGER)");

const big = db.prepare("SELECT id, bytes FROM logs WHERE id > ?").get(2n ** 52n);
// id 可能以 BigInt 返回——比较与序列化前先归一化
const id = typeof big.id === "bigint" ? Number(big.id) : big.id;

db.prepare("INSERT INTO logs(bytes) VALUES (?)").run(1_000_000n); // BigInt 直插安全

规则很简单:主键可能超过 2^53 的系统(雪花 ID、时间戳纳秒)一律按 BigInt 处理,JSON 序列化前显式转 string,否则会在边界值上静默丢精度。

三、什么场景该用,什么场景别用

适合:

  • CLI/桌面应用的状态与历史记录;
  • 服务进程内的结构化缓存(替代手写 Map + TTL);
  • 单机采集器的缓冲队列(WAL + 事务批量落盘);
  • 规则引擎/配置快照的本地镜像。

不适合:

  • 多进程共享写:node:sqlite 没有连接池与等待队列,锁冲突直接抛 SQLITE_BUSY;
  • 大并发 Web 后端的持久层(该走真正的数据库服务);
  • 需要复制、备份到远端、在线 DDL 的场景。

锁冲突兜底模板:

db.exec("PRAGMA busy_timeout = 2000;");   // 先给内核等待窗口

function runTx(fn) {
  for (let i = 0; i < 5; i++) {
    try {
      db.exec("BEGIN IMMEDIATE");
      fn();
      db.exec("COMMIT");
      return;
    } catch (e) {
      db.exec("ROLLBACK");
      if (!String(e.message).includes("SQLITE_BUSY")) throw e;
      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50 * (i + 1));
    }
  }
  throw new Error("sqlite busy: too many retries");
}

BEGIN IMMEDIATE 提前拿写锁,避免"读到一半升级写锁失败"的经典死锁放大。

四、与 Worker Threads 的配合

同步 API 意味着慢查询会阻塞事件循环。两种隔离方式:

其一,把 SQLite 放 worker_threads,主线程通过消息队列访问;其二,坚持"只用毫秒级操作"的纪律——索引点查、小事务批量写,把扫描类查询挪走。

// worker 侧骨架
const db = new DatabaseSync(process.env.DB_PATH);
db.exec("PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL;");
parentPort.on("message", ({ id, sql, params }) => {
  try { parentPort.postMessage({ id, rows: db.prepare(sql).all(...params) }); }
  catch (err) { parentPort.postMessage({ id, error: err.message }); }
});

WAL 模式下"一写多读"跨进程可行,但多个写进程仍是反模式。

五、备份与迁移

没有 pg_basebackup 这类工具,备份就是文件级:SQLite 官方推荐用 backup API;在 node:sqlite 里最稳妥的做法是 checkpoint 后复制:

db.exec("PRAGMA wal_checkpoint(TRUNCATE);");   // WAL 内容并入主库文件
// 然后原子复制 db 文件(同文件系统 rename 或流式拷贝)

备份一致性窗口内不要有写事务;生产节奏建议 cron 每日 checkpoint + 拷贝,配合应用层的导入导出命令做逻辑备份。

六、可观测与调试

  • PRAGMA integrity_check 纳入定期维护;
  • EXPLAIN QUERY PLAN 在 REPL 里随手核对索引命中;
  • Node 内置的 SQLite 版本可用 process.versions.sqlite 确认,升级 Node 时留意它的 changelog(驱动语义基本不变,但默认 PRAGMA 偶有调整)。

小结

node:sqlite 的定位是进程内嵌入式存储,不是"Node 里的 MySQL"。用对的场景(单机、小数据、短操作)它能把一整类 sidecar 依赖从架构里删掉;越界使用(多写进程、长查询阻塞事件循环、BigInt 精度失控)则是三类典型事故。记住四条纪律:prepare 复用参数绑定、超 2^53 一律 BigInt、写路径 BEGIN IMMEDIATE + busy_timeout、慢操作进 worker_threads。

读完了?给作者一点支持

本文采用 CC BY 4.0 协议转载 · © 云边小卖部

评论(0)

登录 后参与评论。

  • 还没有评论,来抢沙发。

🔗 相关文章

审计人的职业规划地图:事务所、企业内审、监管与自由执业的四条路线

"做了三年审计接下来去哪"是行业论坛上的永恒问题。2026 年的就业市场给出了新的答案坐标:AI 压缩了基础核算与核对类岗位,同时抬高了风险判断、内控体系、数据审计类岗位的身价。本文把审计人的出路整理成四条主路线——事务所纵深、企业内审/风控、监管与准则机构、自由执业/专家证人——每条给进入条件、典型轨迹、5 年收入区间感与适配画像,帮你做一次结构化的自我定位。

1 天前👍 1

AI 正在怎样改变审计工作:一份可落地的工具地图与边界清单

"AI 取代审计师"是标题党,"AI 不改审计流程"是天真的。2026 年的真实图景是:审计的每个环节都出现了成熟度不一的 AI 应用——有的已进四大方法论并受监管审视(分析程序、抽凭),有的仍处试点(风险评价辅助),有的干脆不该用(对管理层意图的判断)。本文按审计流程逐环节给出一份工具地图:能做什么、成熟度如何、边界在哪,以及从业者该怎么上手。

1 天前👍 1

内部审计的转型:从合规检查到持续审计,2026 年的方法论与落地路径

企业内部审计正经历十年来最大的一次定位调整:监管趋严(上市公司内控规范迭代、"十五五"会计规划对行业数字化基建的明确指向)加上 AI 工具成熟,让传统"年度计划 + 现场抽查"模式的价值密度持续下降。领先实践已经给出替代方案:风险导向的动态审计计划 + 持续审计(continuous auditing)+ 咨询角色。本文给企业内审负责人与准备进入内审的事务所人士一套转型方法论:架构怎么搭、数据管道怎么建、异常规则库怎么运营、以及如何向审计委员会证明价值。

1 天前👍 1