di-框架:sqlite-SQLite WebAssembly组件

捆绑 SQLite(模拟3.53.2)和 将它通过 di-framework:[email protected] 怀特 软件包。 数据库文件在 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:[email protected]
├── 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

大楼

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,即:

. 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 拒绝漂流.

环境覆盖

WIT 接口 (di-framework:[email protected](中文(简体) )

全文在 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/[email protected]; 到生成的来宾 组织sqliteProjectRequirements() 内 src/wit.ts 这样做).

2. 联合来文数字 : componentize-qjs/jco 将导入显示为 ES 模块:

   import { open } from 'di-framework:sqlite/[email protected]';
   
   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 值为 bigints. A类 MigrationDatabase.transaction(fn) 包装 地图到 begin编号 :commit编号 :rollback (或 savepoint 当它已经在里面了.

3. 编曲 组件后 :

   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:[email protected] (用于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 此软件包不支持.