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。
评论(0)
登录 后参与评论。