# @di-framework/sqlite-component 中文文档

规范地址：https://npmcn.com/package/%40di-framework/sqlite-component/

版本：6\.0\.30
npm 元数据更新时间：2026-11-06T22:52:27.787Z
中文译文更新时间：2026-11-12T06:26:14.818Z
软件包许可：\(MIT OR Apache-2\.0\)

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40di-framework/sqlite-component
原文对照：https://npmcn.com/package/%40di-framework/sqlite-component/?lang=original
项目主页：https://github.com/di-framework/platform
源码仓库：https://github.com/di-framework/platform

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.3 MB，9 个文件
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2026-09-27T23:03:05.049Z
- 最新版本发布：2026-11-06T22:52:27.480Z
- 近 30 天下载量：3671（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

SQLite WebAssembly组件(di-framework:sqlite@0.1.0)供平台嘉宾使用.

## 安装

```sh
npm install @di-framework/sqlite-component
```

也可以使用：`pnpm add @di-framework/sqlite-component`、`yarn add @di-framework/sqlite-component`、`bun add @di-framework/sqlite-component`

## README

# di-框架:sqlite-SQLite WebAssembly组件

捆绑 SQLite(模拟3.53.2)和 将它通过 `di-framework:sqlite@0.1.0` 怀特 软件包。 数据库文件在 WASI 文件系统上运行 组件(挂载体积),使用回滚日记 `synchronous=FULL`。 。 。 .

它的存在因此基于QuickJS的 二框架应用组件(由 `componentize-qjs` 内 `@di-framework/cli-plugin-platform`)可以坚持演员 状态、排队作业和移民簿记,在联署材料中没有本地 SQLite 运行时间:联署材料部分 _进口_ `di-framework:sqlite/database`这个 组件 _出口_ 它,和 `wac plug` 把它接入一个部件.

```
┌──────────────────────────────┐   di-framework:sqlite/database   ┌────────────────────────────┐
│ app.wasm (componentize-qjs)  │ ───────── import ──────────────▶ │ di-framework-sqlite.wasm   │
│  imports wasi:http, ...      │                                  │  exports database, types   │
└──────────────────────────────┘                                  │  imports wasi:filesystem,  │
                 └────────────── wac plug ────────────────────────┤          wasi:clocks, cli  │
                                    │                             └────────────────────────────┘
                                    ▼
                          composed.wasm  (only wasi:* / wasmcloud:* imports remain)
```

## 版式

```
packages/di-framework-sqlite-component/
├── Cargo.toml, Cargo.lock        pinned crates (rusqlite 0.40.2, libsqlite3-sys 0.38.2, wit-bindgen 0.61.1, cc 1.4.5)
├── rust-toolchain.toml           Rust 1.97.1 + wasm32-wasip2 (honoured by rustup)
├── .cargo/config.toml            default target + C toolchain env + SQLite compile flags
├── build.rs                      compiles csrc/wasi-vfs.c with the same wasi-sdk clang
├── csrc/wasi-vfs.c               SQLite VFS over wasi-libc (see "Persistence model")
├── wit/world.wit                 di-framework:sqlite@0.1.0
├── src/lib.rs                    the component (exports database + types)
├── scripts/
│   ├── tool-versions.env         every pinned version + SHA-256
│   ├── install-tools.sh          checksum-verified installer for wasm-tools, wac, wasi-sdk (+ optional rustup)
│   ├── env.sh                    puts .tools/ on PATH and exports build env (sourceable)
│   ├── build.sh                  cargo build + validate + stage dist/
│   ├── compose.sh                wac plug <consumer> with the provider
│   └── smoke.sh                  end-to-end test under wasmtime
├── tests/smoke-consumer/         wasip2 command component importing the interface (used by smoke.sh)
├── Makefile                      thin wrapper around the scripts
└── dist/  (generated)            di-framework-sqlite.wasm, .wit, BUILD-INFO.txt, SHA256SUMS
```

## 大楼

```sh
cd packages/di-framework-sqlite-component

make tools        # wasm-tools 1.258.0, wac 0.11.0, wasi-sdk 34.0 -> .tools/ (SHA-256 verified)
make tools-rust   # only if you have no rustup: hermetic rustup + Rust 1.97.1 + wasm32-wasip2 -> .tools/
make build        # -> dist/di-framework-sqlite.wasm (~1.2 MB)
make smoke        # compose with tests/smoke-consumer and run under wasmtime (needs `wasmtime` on PATH)
```

`make build` 运行 `scripts/build.sh`,即:

```sh
. scripts/env.sh                                     # PATH, CC_wasm32_wasip2, LIBSQLITE3_FLAGS, RUSTFLAGS
cargo build --locked --release --target wasm32-wasip2 -p di-framework-sqlite-component
wasm-tools validate --features all dist/di-framework-sqlite.wasm
wasm-tools component wit dist/di-framework-sqlite.wasm > dist/di-framework-sqlite.wit
```

要求:目标汇编器 `wasm32-wasip2` 带有 isti-libc 标题 (被钉住的isi-sdk; Apple Clang 没有后端) `wasm32-wasip2` 斯特德,你说什么, `wasm-tools`。 。 。 . `rustc` 打开 `wasm32-wasip2` 发射组件 直接(通过) `wasm-component-ld`因此没有 `wasm-tools component new` 步骤是 需要帮助。 建筑具有决定性: `--remap-path-prefix` 切除绝对路径 财务报告和审定财务报表 `dist/SHA256SUMS` 在同一个工具链上的干净重建是相同的.

### 固定和校验和

`scripts/tool-versions.env` 是真理的唯一来源. `install-tools.sh` 下载后从 GitHub / status.rust-lang.org 中释放资产,比较 SHA-256与钉入值 **在此之前** 解开或执行任何东西, 并终止错配。 macOS(arm64, x86 64) 和 Linux 的哈什记录 (x86 64,无锡64). 要升级: 刷新版本,下载新资产, `shasum -a 256`,更新文件,重建,运行 `make smoke`。 。 。 .

灰尘本身被 `rust-toolchain.toml` (破损核实组件) 以已签的信道为准。 铁柜被钉住 `=` 内 `Cargo.toml` 锁入 `Cargo.lock`· ; `--locked` 拒绝漂流.

### 环境覆盖

| 变量 | 含义 |
| --- | --- |
| `DF_SQLITE_TOOLS_DIR` | 地点 `install-tools.sh` 安装( 默认) `.tools/`(中文(简体) ) |
| `WASI_SDK_PATH` | 使用已有的 idi- sdk 而不是下载 |
| `CC_wasm32_wasip2`, (中文(简体) ), `AR_wasm32_wasip2`, (中文(简体) ), `CFLAGS_wasm32_wasip2` | C 工具链 `sqlite3.c` + 键 `wasi-vfs.c` |
| `LIBSQLITE3_FLAGS` | 额外 `-D` 组合的旗帜(见 `.cargo/config.toml`(中文(简体) ) |

## WIT 接口 (`di-framework:sqlite@0.1.0`(中文(简体) )

全文在 [`wit/world.wit`](https://npmcn.com/package/%40di-framework/sqlite-component/wit/world.wit)总结:

**`types`**

-   `value`数字 : `null | integer(s64) | real(f64) | text(string) | blob(list<u8>)`
-   `row = list<tuple<string, value>>` —列名/值对,按列顺序排列
-   `error`数字 : `open-failed(string) | closed | invalid-sql(string) | invalid-params(string) | execution-failed(sqlite-error) | value-conversion-failed(string) | busy | invalid-transaction-state(string) | other(string)`
-   `sqlite-error { code, extended-code, message }` - 比如说. `19`编号 :`1555` 违反主要规定
-   `open-options { create?, read-only?, synchronous?, journal-mode?, busy-timeout-ms?, foreign-keys? }`
-   语句 `sync-mode { off, normal, full }`, (中文(简体) ), `journal-mode { delete, persist, memory }`, (中文(简体) ), `transaction-behavior { deferred, immediate, exclusive }`

**`database`**

-   `open(path, option<open-options>) -> result<connection, error>`
-   `sqlite-version() -> string`
-   `resource connection`
    -   `exec(sql)` ——多报表批次,无参数,无结果(DDL / 迁移/平板)
    -   `run(sql, params) -> u64` ——一个语句,返回 `changes`
    -   `query(sql, params) -> list<row>`
    -   `first(sql, params) -> option<row>`
    -   `begin(option<transaction-behavior>)` (默认) `immediate`, (中文(简体) ), `commit()`, (中文(简体) ), `rollback()`
    -   `savepoint(name)`, (中文(简体) ), `release-savepoint(name)`, (中文(简体) ), `rollback-to-savepoint(name)` - 筑巢
    -   `in-transaction() -> bool`, (中文(简体) ), `changes() -> u64`, (中文(简体) ), `last-insert-rowid() -> s64`
    -   `close()`

**世界**数字 : `sqlite-provider { export types; export database; }` (本部分) 财务报告和审定财务报表 `imports { import types; import database; }` (消费者).

应用的默认 `open` 当选项被省略时 : `journal_mode=DELETE`, (中文(简体) ), `synchronous=FULL`, (中文(简体) ), `foreign_keys=ON`, (中文(简体) ), `busy_timeout=5000`。 。 。 . `open` 核查 日记模式 SQLite 报告匹配请求,否则失败.

## 持久性模式

-   **滚回日记,不是WAL.** WAL 需要共享内存和文件锁定 WASI文件系统也没有提供. `sqlite3.c` 编译为 `-DSQLITE_OMIT_WAL`这样 `PRAGMA journal_mode=WAL` 是一个沉默的不开放和 连接保持 `delete`。提供的模式: `delete` (违约), `persist`, (中文(简体) ), `memory` (只有测试).
-   **`synchronous=FULL` 默认** (单位:千美元)`-DSQLITE_DEFAULT_SYNCHRONOUS=2` 设置 。 。 。 每个任务通过日记和数据库同步 `wasi:filesystem/types.descriptor.sync`。 。 。 . `normal` 可通过 `open-options` 用于耐久性较低的工作量.
-   **单行作家.** VFS没有锁定. 内部每个文件一个连接 和每个主机文件的组件实例 执行 wasmCloud 插件 `replicas: 1` 演员工作量 (单位:千美元)`WASMCLOUD_ACTORS_REPLICA_CONSTRAINT`) (中文(简体) ).
-   **路径是预开口内的来宾路径.** 库伯内特家族的标志是 聚氯乙烯在 `mountPath` (默认) `/data/actors`并揭露同样的路径 来宾; 打开 `/data/actors/<db>.sqlite`。任何预打开失败的路径 `open-failed`。 。 。 .
-   **没有临时文件.** `-DSQLITE_TEMP_STORE=3` 财务报告和审定财务报表 `-DSQLITE_STMTJRNL_SPILL=-1` 保留临时表格、分拣器和报表日记.

### 家庭服务基金`csrc/wasi-vfs.c`(中文(简体) )

`libsqlite3-sys` 船舶a `wasm32-wasi-vfs` c文件为2010年时代的特性 sQLite 副本 `demovfs.c`这是 **没有** 此处使用的原因是:

1.  联合国 `xFileControl` 返回时 `SQLITE_OK` 自 SQLite 3.7.x 以来 `PRAGMA` 首先通过 `SQLITE_FCNTL_PRAGMA`,则 `OK` 回复 意思是"处理",所以 _每一个PRAGMA 变成一个不op_ (单位:千美元)`journal_mode`, (中文(简体) ), `synchronous`, (中文(简体) ), `user_version`(......) ; (......);
2.  `xTruncate` 是无操作( 除 DELETE 外, 任何日记模式都不安全; VACUUM 永远不会 缩小文件;
3.  `xRandomness` 返回无 en; `xDelete` 扫描其缓冲器的末端.

`csrc/wasi-vfs.c` 同一个公共领域设计与这些固定 (单位:千美元)`SQLITE_NOTFOUND`, (中文(简体) ), `ftruncate`, (中文(简体) ), `getentropy`, (中文(简体) ), `pread`编号 :`pwrite`微秒精确度 `xCurrentTimeInt64`),由 `build.rs` 反对 `libsqlite3-sys`已导出 `sqlite3.h`。 。 。 . `sqlite3.c` 以 `-DSQLITE_OS_OTHER=1` 所以它叫我们 `sqlite3_os_init`。 。 。 . `make smoke` 声称 那个 `PRAGMA journal_mode` 真实返回 `delete` 没有 `-wal` 或停滞 `-journal` 文件被留下.

## 摘自联合来文部分

1.  **怀特**页:1 `wit/world.wit` 改为 `cli-extensions/packages/cli-plugin-platform/assets/wit/deps/di-framework-sqlite/package.wit` 添加 `import di-framework:sqlite/database@0.1.0;` 到生成的来宾 组织`sqliteProjectRequirements()` 内 `src/wit.ts` 这样做).
    
2.  **联合来文**数字 : `componentize-qjs`/jco 将导入显示为 ES 模块:
    
    ```ts
    import { open } from 'di-framework:sqlite/database@0.1.0';
    
    const db = open('/data/actors/orders.sqlite', undefined); // options optional
    db.exec('CREATE TABLE IF NOT EXISTS kv (k TEXT PRIMARY KEY, v TEXT NOT NULL)');
    db.run('INSERT OR REPLACE INTO kv VALUES (?1, ?2)', [
      { tag: 'text', val: 'a' },
      { tag: 'text', val: JSON.stringify({ n: 1 }) },
    ]);
    const row = db.first('SELECT v FROM kv WHERE k = ?1', [{ tag: 'text', val: 'a' }]);
    // row: [['v', { tag: 'text', val: '{"n":1}' }]] | undefined
    
    db.begin(undefined);            // BEGIN IMMEDIATE
    try { /* ... */ db.commit(); } catch (e) { db.rollback(); throw e; }
    ```
    
    `result<_, error>` 失败表面抛出 `ComponentError`谁 `payload` 这是 `error` 变种 (`{ tag: 'execution-failed', val: { code, extendedCode, message } }`) (中文(简体) ). `integer` 值为 `bigint`s. A类 `MigrationDatabase.transaction(fn)` 包装 地图到 `begin`编号 :`commit`编号 :`rollback` (或 `savepoint` 当它已经在里面了.
    
3.  **编曲** 组件后 :
    
    ```sh
    scripts/compose.sh path/to/app.wasm path/to/app.composed.wasm  # = wac plug --plug dist/di-framework-sqlite.wasm app.wasm -o ...
    ```
    
    `wac plug` 连接提供者的每次导出到匹配的导入 应用程序; 组件仅保留 `wasi:*`编号 :`wasmcloud:*` 进口 为宿主. `compose.sh` 失败, 如果 `di-framework:sqlite/database` 仍然是 之后进口.
    
4.  **运送文物**: 插件包构建运行 `make publish-asset`, (中文(简体) ), 从源头建立供应商,复制WASM,回收WIT, 将元数据并校验和输入 `cli-extensions/packages/cli-plugin-platform/dist/assets/sqlite/`。这些生成 npm 包中的文件船,被 Git 忽略。 没有预建的提供者 检查到源树.
    

### WASI 版本注释

本构成部分目标 `wasm32-wasip2` (进口) `wasi:*@0.2.9`),是唯一一个 稳定 Rust 组件目标。 该插件的JS组件目标WASI0.3. `wac plug` 编成精细的部件,然后进口 `wasi:filesystem@0.2.9` (用于SQLite)和0.3.0接口(用于应用) - 不过 _东道主_ 必须提供两者。 hemtime does(p2和p3链接共存); 在您部署的 hamCloud 主机版本中验证此内容 。 当一个马厩 `wasm32-wasip3` 粗糙的目标地,改变 `RUST_TARGET` 内 `scripts/tool-versions.env` 财务报告和审定财务报表 `.cargo/config.toml` 是唯一需要更改的地方 在这里.

## 核查

`make smoke` 正在建设 `tests/smoke-consumer` 联合国 `wasip2` 命令组件 输入接口,用被绑定的键与提供者一起编译 `wac`, (中文(简体) ), 并运行在下面 `wasmtime run --dir <tmp>::/data`它检查: 平板电脑 缺省数(`delete`/FLL/外国密钥),WAL编译出,DDL通过 `exec`, (中文(简体) ), 全部 `value` 各种往返旅行, `changes`编号 :`last-insert-rowid`,错误映射 (约束代码19/1555,语法 ~) `invalid-sql`———————— `invalid-params`, (中文(简体) ), 多报表 ∗ `invalid-sql`, (中文(简体) ), `commit` 无 `begin` → `invalid-transaction-state`),交易,储蓄点和回滚, `close`, (中文(简体) ), 重开只读( e)`SQLITE_READONLY` =8个), `open-failed` 丢失 打开前的目录和路径, `:memory:`,最后说 `.sqlite` 文件存在于主机上, 没有 `-journal`编号 :`-wal` 左边.

## 已知的限制/后续行动

-   同步接口( 无) `async func`/流;小结果罚款 设定框架问题,并匹配 `bun:sqlite`\- 典型的司机.
-   `row` 每行重复列名; 切换到 a `{columns, rows}` 记录如果 大结果总是重要.
-   没有全天候的报表缓存 `run`编号 :`query` 准备一次).
-   `wasmtime` 用于 `make smoke` 此软件包不支持.

## 常见问题

### @di-framework/sqlite-component 是什么？

SQLite WebAssembly组件\(di-framework:sqlite@0\.1\.0\)供平台嘉宾使用\.

### 如何安装 @di-framework/sqlite-component？

在项目目录运行 npm install @di-framework/sqlite-component，或使用 pnpm add / yarn add / bun add。

### @di-framework/sqlite-component 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/di-framework\_\_sqlite-component 是否存在。

### @di-framework/sqlite-component 可以商用吗？

@di-framework/sqlite-component 使用 \(MIT OR Apache-2\.0\) 许可。可在 MIT、Apache-2\.0 中任选其一遵守。选择 MIT 时，宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @di-framework/sqlite-component 的下载量有多少？

根据 npm 官方下载统计，@di-framework/sqlite-component 在 2026/10/12 – 2026/11/10 这 30 天内被下载 3,671 次，日均约 122 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @di-framework/sqlite-component 还在维护吗？

最新版本 6\.0\.30 发布于 2026/11/07（5 天前）；至今共发布 28 个版本，其中过去 12 个月发布了 28 个；首次发布于 2026/09/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。