Spin 内置 SQLite 接口:从 SIP 013 提案到零配置数据库的完整实现指南

原创2026-10-07 14:18:351,915 阅读
文章标签:云原生微服务

Spin 内置 SQLite 接口:从 SIP 013 提案到零配置数据库的完整实现指南

导读

Spin 是开源生态中用于构建和运行 WebAssembly 无服务器应用的开发者工具。本文将围绕其官方设计提案 SIP 013(docs/content/sips/013-sqlite.md)展开,系统讲解 Spin 如何为 Wasm 组件提供内置的 SQLite 数据库访问能力:从提案动机、WIT 接口设计、spin.toml 权限模型、运行时配置文件格式,到 spin up --sqlite 启动迁移机制的完整落地实现。读完本文,你将掌握在 Spin 应用中声明、授权、配置并访问 SQLite 数据库的完整实战流程,并能从源码层面理解 open/execute 的底层调用链与最小能力约束。


一、背景:为什么 Spin 需要内置 SQLite 接口

1.1 动机:从"自带数据库"到"零配置"

SIP 013 指出,在它提出时 Spin 已支持 MySQL 与 PostgreSQL 两种数据库类型,但二者都要求用户自行提供数据库实例,再通过 SDK 将连接暴露给组件。这本质上是 WASI sockets 尚不支持前的过渡方案——一旦 sockets 就绪,用户可以自带任意客户端库连接任意数据库,Spin 无需再为每种数据库定制专用客户端。

SQLite 与上述两种数据库形成鲜明对比:

  • 本地部署可以轻松使用本地 SQLite 数据库文件;
  • 托管部署环境(如 Fermyon Cloud)可以因此实现轻量化的 SQLite 后端;
  • 对用户而言,使用 SQL 数据库时可以获得真正的 "零配置"体验。

换句话说,SQLite 接口的引入让"开箱即用、无需运维外部数据库"成为可能,这正是 SIP 013 提案的核心价值。

1.2 与 wasi-sql 的关系

SIP 013 明确承认 wasi-sql 是一个进行中的通用 SQL 接口规范,目标是覆盖"80% 用户应用的常见功能"。但提案给出了坚持专用 SQLite 接口的两点理由:

  1. 覆盖剩余的 20%:当 wasi-sql 过于通用、无法表达某些 SQLite 特有语义时,专用接口可以补齐这些能力;
  2. 反哺上游:wasi-sql 规范仍在积极探讨如何支持多种 SQL 方言,Spin 的 SQLite 实现可以澄清相关问题并推动上游进展。

提案还特别说明:接口设计以 wasi-sql 为起点,但会刻意调整以贴合 SQLite 语义——这样既不会盲目实现 wasi-sql 的早期版本,也能在接口差异出现时给出合理解释。

1.3 从提案到落地的演进

需要说明的是,SIP 013 写于 2023 年 4 月,文中标注的 WIT 语法"与 Spin 当前使用的 wit-bindgen 版本一致,相对最新 WIT 规范已过时"。而当前仓库中该接口已经升级为符合最新 WIT 规范的 resource 语法(详见下文),提案中的伪资源句柄设计最终以真正的 WIT resource 形式落地,体现了设计思路的一脉相承。


二、接口设计:WIT 文件详解

2.1 提案中的原型 WIT(pseudo-resource 时代)

SIP 013 最初的接口草案采用了当时 Spin 的 WIT 语法,核心设计是伪资源句柄:

// A handle to an open sqlite instance
type connection = u32

// The set of errors which may be raised by functions in this interface
variant error {
  no-such-database,
  access-denied,
  invalid-connection,
  database-full,
  io(string)
}

// Open a connection to a named database instance.
// If `database` is "default", the default instance is opened.
open: func(name: string) -> expected<connection, error>

// Execute a statement
execute: func(conn: connection, statement: string, parameters: list<value>) -> expected<unit, error>

// Query data
query: func(conn: connection, query: string, parameters: list<value>) -> expected<query-result, error>

// Close the specified `connection`.
close: func(conn: connection)

record query-result {
  columns: list<string>,
  rows: list<row-result>,
}

record row-result {
  values: list<value>
}

variant value {
  integer(s64),
  real(float64),
  text(string),
  blob(list<u8>),
  null
}

提案说明,这种"用 open 创建、用 close 释放、句柄作为每个操作第一参数"的模式,与 wasi-sql 及 key-value 存储一致,其灵感来自 WASI preview 2 中同类函数的接口。

2.2 落地后的 WIT:spin:sqlite@3.0.0

该接口在仓库中已正式定型为 wit/deps/spin-sqlite@3.0.0/sqlite.wit,包名为 spin:sqlite@3.0.0,并改用最新的 resource 语法:

package spin:sqlite@3.0.0;

interface sqlite {
  /// A handle to an open sqlite instance
  resource connection {
    /// Open a connection to a named database instance.
    /// If `database` is "default", the default instance is opened.
    /// `error::no-such-database` will be raised if the `name` is not recognized.
    open: static func(database: string) -> result<connection, error>;

    /// Execute a statement returning back data if there is any
    execute: func(statement: string, parameters: list<value>) -> result<query-result, error>;

    /// The SQLite rowid of the most recent successful INSERT on the connection, or 0 if
    /// there has not yet been an INSERT on the connection.
    last-insert-rowid: func() -> s64;

    /// The number of rows modified, inserted or deleted by the most recently completed
    /// INSERT, UPDATE or DELETE statement on the connection.
    changes: func() -> u64;
  }

  variant error {
    no-such-database,
    access-denied,
    invalid-connection,
    database-full,
    io(string)
  }

  record query-result {
    columns: list<string>,
    rows: list<row-result>,
  }

  record row-result {
    values: list<value>
  }

  variant value {
    integer(s64),
    real(f64),
    text(string),
    blob(list<u8>),
    null
  }
}

对照提案可清晰看到演变:

提案草案 落地实现 说明
type connection = u32 resource connection 伪句柄升级为正式 WIT resource
open: func(name) -> ... open: static func(database) -> ... 成为 resource 的静态构造函数
close: func(conn) resource 自动 drop 生命周期由 resource 机制管理
execute 返回 unit execute 返回 query-result 统一了查询与执行路径
— last-insert-rowid / changes 新增 SQLite 特有元数据查询

此外,接口中 execute 与 query 在提案中"是否冗余"的开放问题,落地时通过合并为单一的 execute(返回 query-result,无数据时为空结果)得到了解决。

2.3 值类型与错误模型

  • value 变体覆盖了 SQLite 的核心类型系统:integer(s64)、real(f64)、text(string)、blob(list<u8>)、null,完全对应提案设计;
  • error 变体包含 no-such-database、access-denied、invalid-connection、database-full、io(string) 五种错误,与提案逐字对应。

三、源码实现:主机端调用链

3.1 factor 架构下的 SqliteFactor

当前 Spin 采用 factors 架构(参见 docs/content/sips/021-spin-factors.md)组织运行时能力。SQLite 能力由 crates/factor-sqlite 提供,核心组件如下:

  • crates/factor-sqlite/src/lib.rs 定义 SqliteFactor,实现 Factor trait:
    • init 中通过 ctx.link_bindings 同时注册 v1、v2、v3 三代 WIT 接口(spin_world::v1::sqlite、v2::sqlite、spin::sqlite3_1_0::sqlite),实现向后兼容;
    • configure_app 阶段读取组件元数据中的允许数据库列表(ALLOWED_DATABASES_KEY,即 "databases"),并调用 ensure_allowed_databases_are_configured 校验所有被引用的数据库都已在运行时配置中定义,否则返回形如 "One or more components use SQLite databases which are not defined." 的错误;
    • prepare 阶段为每个组件实例构建 InstanceState,注入其允许的数据库集合与全局的 connection_creators 映射。
  • crates/factor-sqlite/src/runtime_config.rs 定义 RuntimeConfig:一个 HashMap<String, Arc<dyn ConnectionCreator>>,将数据库标签映射到连接创建器。

3.2 InstanceState 与 open/execute 的实际行为

crates/factor-sqlite/src/host.rs 中的 InstanceState 是每个组件实例的宿主状态:

  • 维护一个 spin_resource_table::Table<Arc<dyn Connection>> 资源表(容量 256),存放该实例打开的所有连接;
  • open_impl 的调用链清晰实现了提案语义:
    1. 检查数据库标签是否在 allowed_databases 中,不在则返回 Error::AccessDenied;
    2. 从 connection_creators 查找对应标签的连接创建器,找不到返回 Error::NoSuchDatabase;
    3. 调用 create_connection 创建真实连接并压入资源表,返回 Resource<Connection> 句柄;
    4. 资源表满时返回 Error::Io("too many connections opened")。
  • execute_impl 通过 self.get_connection(connection) 将资源句柄解引用为真实连接,若句柄无效返回 Error::InvalidConnection,随后调用 conn.query(...) 执行 SQL;
  • 连接关闭由 resource 的 drop 钩子实现(connections.remove(connection.rep())),v1 接口中还保留了显式 close 函数以兼容旧组件。

所有 open/execute 调用都带 OpenTelemetry 埋点(otel.kind = "client"、db.system.name = "sqlite"、sqlite.backend 记录后端摘要),便于分布式追踪。

3.3 抽象层:Connection 与 ConnectionCreator

lib.rs 定义了两个关键抽象:

  • trait Connection:抽象查询、批量执行与元数据操作,包括 query、query_async(流式返回行)、execute_batch、changes、last_insert_rowid,以及用于追踪与日志的 summary();
  • trait ConnectionCreator:create_connection(label) 每次返回全新连接(而非复用),默认实现对底层工厂函数做了一次包装,创建失败时映射为 Error::InvalidConnection。

这两个 trait 的存在,使得**本地磁盘数据库(sqlite-inproc)、libSQL 网络数据库(sqlite-libsql)**都能以统一的接口接入 Spin。


四、内置本地数据库与"default"标签

4.1 每个应用独立的默认数据库

SIP 013 规定:默认情况下每个应用拥有自己独立于其他应用的默认数据库。本地应用中,数据库默认存放在与 spin.toml 同级的隐藏 .spin 目录下;远程部署同样提供默认数据库,具体暴露方式(本地磁盘文件或 Turso 之类的第三方网络数据库)由实现者决定。

在 crates/sqlite/src/lib.rs 的 RuntimeConfigResolver 中可以看到该设计的落地:

  • 解析器接收两个目录参数:default_database_dir(默认数据库存放目录,通常是 .spin 状态目录;传 None 则使用内存数据库)与 local_database_dir(相对路径的解析基准目录);
  • 若用户未在运行时配置中显式定义 default 标签,resolve 会自动为 "default" 标签注入一个指向 sqlite_db.db 文件的连接创建器(DEFAULT_SQLITE_DB_FILENAME = "sqlite_db.db");
  • 本地数据库即 crates/sqlite-inproc 提供的 InProcConnection。

4.2 最小容量约束

SIP 013 的"Implementation requirements"为所有符合规范的实现规定了最低能力门槛,组件可以放心依赖:

  • 至少支持 10,000 行数据;
  • 文本与 blob 大小至少 1 兆字节(MB);
  • 最大列数至少 32 列。

这些下限保证了"零配置"体验的可用性基线。提案遗留的开放问题——"假设的 SQLite 版本"——在源码中也得到了部分回应:连接层通过 InProcConnection(本地)与 LazyLibSqlConnection(libSQL)分别抽象,避免组件代码直接绑定特定 SQLite 版本语义。


五、权限模型:按组件授权数据库

5.1 spin.toml 中的 sqlite_databases

SIP 013 规定:默认情况下,应用的任何组件都不具备任何数据库的访问权,必须通过 spin.toml 的如下语法为每个组件显式授权:

sqlite_databases = ["<database 1>", "<database 2>"]

例如,授予组件访问默认数据库:

[component.hello]
source = "target/wasm32-wasi/release/hello.wasm"
sqlite_databases = ["default"]

在源码中,该键由 crates/factor-sqlite/src/lib.rs 中的 ALLOWED_DATABASES_KEY(元数据键 "databases")读取,解析为 HashSet<String> 后注入对应组件实例的 InstanceState。src/commands/deps.rs 中依赖检查逻辑也会读取该字段(component.sqlite_databases)以推断组件的 SQLite 依赖。

5.2 权限校验的两个层面

从 crates/factor-sqlite/tests/factor_test.rs 的测试用例可以验证两套防护:

  1. 配置期校验(errors_when_non_configured_database_used):若组件声明了 sqlite_databases = ["foo"] 但运行时配置中没有定义 foo,应用构建直接失败,错误信息为 "One or more components use SQLite databases which are not defined.";
  2. 运行期校验(errors_when_database_not_allowed):组件声明 sqlite_databases = [] 时调用 state.sqlite.open("foo") 返回 Error::AccessDenied。

两条防线共同保证了"数据库必须显式配置、组件必须显式授权"的安全模型。


六、运行时配置:[sqlite_database.<name>]

6.1 配置文件格式

SIP 013 给出了运行时配置文件(runtime config TOML)中 SQLite 数据库的配置方式——default 的配置可被覆盖,也可以声明其他数据库:

# The `default` config can be overridden
[sqlite_database.default]
path = ".spin/some-other-database.db"

[sqlite_database.other]
path = ".spin/yet-another-database.db"

6.2 落地实现:类型化配置与后端选择

当前仓库把该配置演进为带 type 字段的格式,由 crates/sqlite/src/lib.rs 的 TomlRuntimeConfig 反序列化(#[serde(deny_unknown_fields)] 严格校验字段):

# 本地磁盘数据库(Spin 默认实现)
[sqlite_database.mydb]
type = "spin"
path = ".spin/my-database.db"
# 可选:是否允许 ATTACH 已存在的文件(默认 false)
allow_attach_file = false

# libSQL 网络数据库(如 Turso),仅支持 HTTP(S) 地址
[sqlite_database.cloud]
type = "libsql"
url = "https://libsql.example.com"
token = "<access token>"
  • type = "spin":本地数据库,路径相对于运行时配置文件所在目录解析(绝对路径原样使用,见 resolve_relative_path);allow_attach_file 默认 false,禁止 ATTACH 已存在的文件(临时文件与 :memory: 的附加始终允许);
  • type = "libsql":libSQL 后端,check_url 强制要求 https:// 或 http:// 前缀,Spin 目前仅支持通过 HTTP(S) 访问 libSQL 数据库;
  • 未知的 type 会直接报错 "Unknown database kind"。

解析得到的 ConnectionCreator 会被放入 RuntimeConfig.connection_creators,最终通过 spin-runtime-factors 装配进 SqliteFactor 的 AppState。这套机制也印证了 SIP 013 中"远程数据库可由实现者选择暴露方式(本地文件或第三方网络数据库)"的设计弹性。


七、数据库迁移:spin up --sqlite 启动执行机制

7.1 CLI 选项

SIP 013 决定:迁移问题暂时通过 spin up 的命令行选项解决——在启动时对默认数据库执行任意 SQL 语句,例如 --sqlite "CREATE TABLE users..."。迁移语句必须由用户保证幂等,重复执行不会产生意外结果。

该选项在源码中的定义位于 crates/runtime-factors/src/lib.rs 的 TriggerAppArgs:

/// Run a SQLite statement such as a migration against the default database.
/// To run from a file, prefix the filename with @ e.g. spin up --sqlite @migration.sql
#[clap(long = "sqlite")]
pub sqlite_statements: Vec<String>,

即支持两种用法:

# 直接内联 SQL 语句(作用于 default 数据库)
spin up --sqlite "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)"

# 从文件读取 SQL(支持 @file 或 @file:label 指定目标数据库)
spin up --sqlite @migrations/001_init.sql
spin up --sqlite @migrations/002_seed.sql:other

@file:label 语法中,标签缺省时默认为 default;解析逻辑(parse_file_and_label)对空文件路径、空标签等非法输入会给出明确错误,其单测见 crates/trigger/src/cli/sqlite_statements.rs 的 test_parse_file_and_label。

7.2 执行时机与实现

SqlStatementExecutorHook(crates/trigger/src/cli/sqlite_statements.rs)实现了 ExecutorHooks::configure_app:

  • 若应用未启用 SqliteFactor,钩子静默忽略;
  • 对每条内联语句,通过 sqlite.get_connection("default") 获取默认数据库并执行 query;
  • 对 @file:label 形式,读取文件内容后调用 database.execute_batch(&sql) 批量执行;
  • 任何失败都会附带上下文错误(如 "failed to execute sql against database '{label}' from file '{file}'")。

该钩子在 crates/runtime-factors/src/build.rs 中通过 args.sqlite_statements.clone() 注入构建流程,因此迁移语句在应用正式提供服务前完成执行。测试 test_execute 验证了混合场景:先对内联语句执行 Query,再对 @file:label 语句执行 Execute,且默认数据库与指定标签分别创建连接。

7.3 未来迁移方案的演进方向

SIP 013 同时列出了一系列替代迁移机制作为未来方向,并指出这些方案并不互斥:

  • 让某些组件先于其他组件运行,组件读取当前 schema 版本并自行决定是否迁移;
  • 组件导出 schema 版本值,版本不匹配时调用导出的 migrate 函数;
  • 在预初始化结束后调用一个专门的迁移组件;
  • 在 spin.toml 中提供配置项(如 sqlite.execute = "CREATE TABLE users...")。

提案最终选择"先通过 CLI 提供最小可行机制,未来再替换为更通用的方案"。当前仓库的实现(--sqlite 与 @file 文件执行)正是这一决定的直接产物。

7.4 被否决的方案及其理由

SIP 013 也记录了一个被明确否决的替代方案:要求用户在每个 trigger handler 运行时手动保证数据库处于正确状态(即完全不做迁移机制)。否决理由有二:

  1. Schema 跟踪方案(如维护一张 "migrations" 表)本身就需要某种 bootstrap 步骤;
  2. 这违背了"保持组件 handler 函数简单、单一职责"的设计原则。

这一取舍说明:迁移能力被视作平台基础设施职责,而非组件业务逻辑的一部分。


八、遗留开放问题与未来工作

SIP 013 诚实记录了提案阶段未决的问题:

  • 大结果集分页:row-result 可能非常大,是否应提供分页机制或允许用户按子集读取?——提案认为跨越 WIT 边界的传输可能昂贵,把读取方式控制权交给用户会有帮助。当前实现以 MAX_HOST_BUFFERED_BYTES(crates/world/src/lib.rs 定义的主机缓冲上限)约束单次返回,并通过 query_async 的流式通道(QueryAsyncResult 携带 tokio::sync::mpsc::Receiver<RowResult>)部分回应了该问题;
  • query 与 execute 是否冗余:落地时已通过合并为单一 execute(返回 query-result)解决;
  • SQLite 版本假设:不同实现间语义可能存在细微差异,需要引导用户选择预期可工作的版本范围。

未来工作方面,提案提到可能尝试统一当前支持的三种 SQL 方言(SQLite、MySQL、PostgreSQL),但同时也提醒:如果统一这三种差异较大的方言反而造成更多困惑,则未必可取。


九、实战示例:完整的 SQLite 应用配置

综合全文,一个使用 SQLite 的 Spin 应用包含三部分配置:

1. spin.toml 中声明并授权数据库:

spin_version = "3"
name = "sqlite-example"
trigger = { type = "http", base = "/" }

[[component]]
id = "api"
source = "target/wasm32-wasi/release/api.wasm"
sqlite_databases = ["default", "analytics"]

2. 运行时配置文件(如 runtime-config.toml)中定义数据库:

[sqlite_database.default]
type = "spin"
path = ".spin/app.db"

[sqlite_database.analytics]
type = "libsql"
url = "https://analytics.turso.io"
token = "your-token"

3. 启动时执行迁移:

spin up --sqlite "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT NOT NULL);" \
        --sqlite @migrations/seed.sql:default

组件内通过 SDK(spin-sdk 的 sqlite API)即可用 open("default") 打开连接、以 execute 携带 value 参数执行参数化 SQL、读取 query-result 的列名与行值。访问未授权数据库将得到 access-denied,访问未配置数据库将得到 no-such-database。


延伸阅读

登录后查看全文
spin