SQLocal

SQLocal 使得在浏览器中运行 SQLite3 变得简单，它由源私有文件系统支持。它封装了 SQLite3 的 WebAssembly 构建，并为您提供了一个简单的接口来与设备上运行的数据库进行交互。

特性

🔎 本地执行 SQLite3 支持的任何查询
🧵 在 Web Worker 中运行 SQLite 引擎，查询不会阻塞主线程
📂 将数据持久化到源私有文件系统，该系统针对快速文件 I/O 进行了优化
🔒 每个用户可以拥有自己的私有数据库实例
🚀 简单的 API；只需命名您的数据库并开始运行 SQL 查询
🛠️ 与 Kysely 和 Drizzle ORM 兼容，用于进行类型安全的查询

示例

import { SQLocal } from 'sqlocal';

// 创建一个客户端，为要保存在源私有文件系统中的 SQLite 文件命名
const { sql } = new SQLocal('database.sqlite3');

// 使用 "sql" 标记模板在 SQLite 数据库中执行 SQL 语句
await sql`CREATE TABLE groceries (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT)`;

// 只需在 SQL 字符串中插入参数即可执行参数化语句
const items = ['bread', 'milk', 'rice'];
for (let item of items) {
  await sql`INSERT INTO groceries (name) VALUES (${item})`;
}

// SELECT 查询和带有 RETURNING 子句的查询将返回匹配的记录作为对象数组
const data = await sql`SELECT * FROM groceries`;
console.log(data);

日志：

[
  { id: 1, name: 'bread' },
  { id: 2, name: 'milk' },
  { id: 3, name: 'rice' }
]

或者，您可以将 SQLocal 用作 Kysely 或 Drizzle ORM 的驱动程序，以进行完全类型化的查询。

Kysely

import { SQLocalKysely } from 'sqlocal/kysely';
import { Kysely, Generated } from 'kysely';

// 初始化 SQLocalKysely 并将方言传递给 Kysely
const { dialect } = new SQLocalKysely('database.sqlite3');
const db = new Kysely<DB>({ dialect });

// 定义您的架构
// （传递给上面的 Kysely 泛型）
type DB = {
  groceries: {
    id: Generated<number>;
    name: string;
  };
};

// 进行类型安全的查询
const data = await db
  .selectFrom('groceries')
  .select('name')
  .orderBy('name', 'asc')
  .execute();
console.log(data);

查看 Kysely 文档以了解入门指南。

Drizzle

import { SQLocalDrizzle } from 'sqlocal/drizzle';
import { drizzle } from 'drizzle-orm/sqlite-proxy';
import { sqliteTable, int, text } from 'drizzle-orm/sqlite-core';

// 初始化 SQLocalDrizzle 并将驱动程序传递给 Drizzle
const { driver } = new SQLocalDrizzle('database.sqlite3');
const db = drizzle(driver);

// 定义您的架构
const groceries = sqliteTable('groceries', {
  id: int('id').primaryKey({ autoIncrement: true }),
  name: text('name').notNull(),
});

// 进行类型安全的查询
const data = await db
  .select({ name: groceries.name })
  .from(groceries)
  .orderBy(groceries.name)
  .all();
console.log(data);

查看 Drizzle ORM 文档以了解声明架构和进行查询。

安装

使用您的包管理器在应用程序中安装 SQLocal 包。

npm install sqlocal
# 或者...
yarn add sqlocal
# 或者...
pnpm install sqlocal

跨源隔离

为了将数据持久化到源私有文件系统，此包依赖于需要跨源隔离的 API，因此使用此包的页面必须使用以下 HTTP 标头进行服务。否则，浏览器将阻止访问源私有文件系统。

Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin

如果您的开发服务器使用 Vite，您可以通过在 Vite 配置中添加以下内容来实现这一点。

plugins: [
  {
    name: 'configure-response-headers',
    configureServer: (server) => {
      server.middlewares.use((_req, res, next) => {
        res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
        res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
        next();
      });
    },
  },
],

Vite 配置

Vite 目前存在一个问题，导致它无法使用默认配置正确加载 Web Worker 文件。如果您使用 Vite，请在 Vite 配置中添加以下内容以修复此问题。

optimizeDeps: {
  exclude: ['sqlocal'],
},