native-sqlite

native-sqlite 提供 bun:sqlite 风格 API，但只依赖宿主运行时自带的 SQLite 能力：

• Bun 导入时走 bun:sqlite
• Node / Deno 导入时走 node:sqlite 包装层
• React Native / Expo 导入时走 expo-sqlite 同步接口包装层

使用

import { Database } from "native-sqlite";

const db = new Database(":memory:");
db.run("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)");
db.run("INSERT INTO users (name) VALUES (?)", "Ada");

const user = db.query("SELECT * FROM users WHERE name = ?").get("Ada");
console.log(user);

在 Expo / React Native 中需要安装 peer dependency：

npx expo install expo-sqlite

文件库名是 Expo 沙盒里的数据库名，不是 Node 文件系统路径。:memory: 仍是内存库；绝对路径会被拆成目录 + 文件名后交给 openDatabaseSync。也可以显式走 Expo 入口：

import { Database } from "native-sqlite/expo";

条件导出

• react-native -> expo.js
• bun -> bun.js
• 默认分支（Node / Deno）-> node.js

兼容范围

已对齐的核心同步接口：

• Database, Statement, SQLiteError, constants, native
• run, exec, query, prepare, transaction
• all, get, iterate, run, values

Node / Deno 分支不会伪造 node:sqlite 没有等价能力的 Bun 特性，下列 API 会显式抛错：

• Database.deserialize()
• Database.setCustomSQLite()
• Database.serialize()
• Database.fileControl()
• Statement.raw()
• Database.handle

Expo 分支用的是 expo-sqlite 同步 API（prepareSync / executeSync / execSync），并会在打开时使用 useNewConnection: true，避免按库名复用连接。和 Node 分支不同，Expo 可以实现：

• Database.serialize()（返回 Uint8Array）
• Database.deserialize()
• Database.loadExtension()（含 entryPoint；Web 不可用）

Expo 仍会显式抛错或不对齐的部分：

• Database.setCustomSQLite()
• Database.fileControl()
• Database.handle
• Statement.raw()
• DatabaseOptions.safeIntegers / bigint 绑定
• 同时传入 named + positional 绑定
• columnTypes / declaredTypes（expo-sqlite 不暴露列类型，返回 null）
• readonly 只能事后执行 PRAGMA query_only = ON，不是 SQLITE_OPEN_READONLY

同步 API 会占用 JavaScript 线程。适配器只承诺 iOS / Android；Expo Web 需要自行保证 SharedArrayBuffer / COOP / COEP。

运行时要求

• Bun：内置 bun:sqlite
• Node：运行时支持 node:sqlite
• Deno：运行时支持 node:sqlite 兼容层
• React Native / Expo：expo-sqlite >= 15，且只使用同步接口

测试

bun run test:bun
bun run test:node
bun run test:expo
deno test --allow-ffi test/node.test.js

当前端到端测试覆盖：

• Bun 和 Node 共用同一套 node:test 用例
• Expo 适配器在 Node / Bun 上通过 expo-sqlite mock 跑同一套合同用例
• Deno 也可以通过 deno test --allow-ffi 运行同一套用例
• 条件导出后的实际包导入
• 基础建表、插入、查询、事务
• Uint8Array 和 Buffer 写入 BLOB 后的 round-trip
• 可空 TEXT / BLOB 字段写入 NULL 后的 round-trip
• all()、get()、iterate()、values() 下的 BLOB 读取结果