sql.js 可以在浏览器中运行SQLite数据库

程序笔记 2024年06月17日09:44

SQL.js是一个JavaScript库，允许您完全在浏览器中创建和查询关系数据库。它使用一个存储在浏览器内存中的虚拟数据库文件，所以它不会持久化对数据库的修改。

SQL.js的核心是一个JavaScript实现的SQLite数据库引擎。 SQLite是一个轻量级的开源关系数据库，它被广泛用于嵌入式系统和移动应用程序。 SQL.js通过将SQLite编译为WebAssembly，使其可以在浏览器中运行。sql.js 允许开发者创建关系数据库并完全在浏览器中查询，而且使用存储在内存中的虚拟数据库文件，因此不会保留对数据库所做的更改。但是，其允许开发者导入任何现有的 sqlite 文件，并将创建的数据库导出为 JavaScript 类型数组。

sql.js 可以像任何传统的 JavaScript 库一样使用，因此如果正在使用 JavaScript 构建本机应用程序（例如使用 Electron），或者正在使用 Node.js 则可能更喜欢使用 SQLite 到 JavaScript 的本机绑定 (Native Binding of SQLite to JavaScript)。

本机绑定不仅速度更快，而且还能够直接处理数据库文件，而不必将整个数据库加载到内存中，从而避免内存不足错误并进一步提高性能。

目前 sql.js 在 Github 通过 MIT 协议开源，有超过 12.2k 的star、1k 的fork、项目依赖量6.8k、代码贡献者 50+ ，妥妥的前端优质开源项目。

如何使用 sql.js

浏览器中使用sql.js

默认情况下，sql.js 使用 wasm，因此除了 javascript 库之外还需要加载 .wasm 文件。从 npm 安装 sql.js 后，开发者可以在

./node_modules/sql.js/dist/sql-wasm.wasm 中找到此文件，并指示捆绑程序将其添加到静态资产或从 CDN 加载。

然后使用传递给 initSqlJs 的配置对象的 locateFile 属性来指示文件所在的位置。如果使用 webpack 等构建器，则可以自动执行此操作。

const initSqlJs = require('sql.js');

const SQL = await initSqlJs({
  // 需要异步加载 wasm 二进制文件
  //  在 node 中运行时可以完全省略 locateFile
  locateFile: file => `https://sql.js.org/dist/${file}`
});

// 创建数据库
const db = new SQL.Database();
// 执行包含多个语句的单个 SQL 字符串
let sqlstr = "CREATE TABLE hello (a int, b char); \
INSERT INTO hello VALUES (0, 'hello'); \
INSERT INTO hello VALUES (1, 'world');";
db.run(sqlstr);
// 准备一条 sql 语句
const stmt = db.prepare("SELECT * FROM hello WHERE a=:aval AND b=:bval");

// 将值绑定到参数并获取查询结果
const result = stmt.getAsObject({':aval' : 1, ':bval' : 'world'});
console.log(result);
// 输出值 {a:1, b:'world'}

stmt.bind([0, 'hello']);
stmt.free();
const res = db.exec("SELECT * FROM hello");
/* 输出
[
  {columns:['a','b'], values:[[0,'hello'],[1,'world']]}
]
*/
db.create_aggregate(
  "json_agg",
  {
    init: () => [],
    step: (state, val) => [...state, val],
    finalize: (state) => JSON.stringify(state),
  }
);
db.exec("SELECT json_agg(column1) FROM (VALUES ('hello'), ('world'))");
// -> 输出值 '["hello","world"]'

// 将数据库导出到包含 SQLite 数据库文件的 Uint8Array
const binaryArray = db.export();

Node.js 环境中使用sql.js

sql.js 托管在 npm 上，只需运行 npm install sql.js 即可。或者，开发者可以简单地从下面的下载链接下载 sql-wasm.js 和 sql-wasm.wasm。

在 Node.js 环境中，可以通过下面代码从磁盘读取数据库：

const fs = require('fs');
const initSqlJs = require('sql-wasm.js');
const filebuffer = fs.readFileSync('test.sqlite');

initSqlJs().then(function(SQL){
  // 读取 DB
  const db = new SQL.Database(filebuffer);
});

同时，可以通过下面方法将内容写入磁盘：

const fs = require("fs");
// [...] (create the database)
const data = db.export();
const buffer = Buffer.from(data);
fs.writeFileSync("filename.sqlite", buffer);

同时，如果开发者不想在主应用程序线程中运行 CPU 密集型 SQL 查询，则可以使用更受限制的 WebWorker API。

const worker = new Worker("/dist/worker.sql-wasm.js");
  worker.onmessage = () => {
    console.log("Database opened");
    worker.onmessage = event => {
      console.log(event.data);
      // 查询结果
    };

    worker.postMessage({
      id: 2,
      action: "exec",
      sql: "SELECT age,name FROM test WHERE id=$id",
      params: {"$id": 1}
    });
  };

  worker.onerror = e => console.log("Worker error:", e);
  worker.postMessage({
    id:1,
    action:"open",
    buffer:buf,
     /* 可选，代表 SQLite 数据库文件的 ArrayBuffer*/
  });

sql.js 还支持与 XMLHttpRequest 一起使用，比如下面的示例：

const xhr = new XMLHttpRequest();
// For example: https://github.com/lerocha/chinook-database/raw/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqli