gosuda.org/sqlite3: A Drop-In database/sql Driver Running Native C SQLite Over Shared Memory

gosuda.org/sqlite3 是一个用于 Go 的 CGO_ENABLED=0 database/sql 驱动程序，它通过 HQQ 共享内存环，在一个隔离的工作进程中运行上游的 C SQLite 3.54.1 合并代码。它注册在标准的 "sqlite3" 驱动名称下，支持 github.com/mattn/go-sqlite3 DSN 查询参数，内嵌了针对六个操作系统和架构目标的 SLSA 认证的预构建服务器二进制文件，并使用带有 64 KiB 批次预取功能的请求流水线，从而在多行查询中超越了进程内的 cgo 性能。

1go get gosuda.org/sqlite3@v0.3.3540100

为什么需要另一个 Go SQLite 驱动程序？

SQLite 是世界上部署最广泛的软件之一，然而从 Go 中使用它历来迫使工程师在构建简单性和引擎保真度之间做出令人不悦的选择。

一方面是 github.com/mattn/go-sqlite3，这是长久以来的社区标准。它通过 cgo 直接包装了官方的 C SQLite 合并代码。你可以获得真正的 C 查询规划器、完整的 WAL 并发语义以及可预测的 C 内存管理。其代价是 CGO_ENABLED=1：本地构建和 CI 管道变慢，最小化的 scratch 或 distroless 容器镜像需要匹配的 C 运行时库，交叉编译到另一个操作系统或 CPU 架构需要完整的 C 交叉工具链，并且 C 中的任何内存损坏都会共享 Go 进程地址空间。

另一方面是纯 Go 的 SQLite 移植版本，它们通过在模拟的 C 运行时 (libc) 上将 C 合并代码机械地翻译成 Go 源代码来生成。它们恢复了 CGO_ENABLED=0，这使得构建变得微不足道。然而，在持续的工作负载下，翻译后的 C 堆和每行 Go 分配会增加垃圾回收压力，并且在锁定、繁忙超时或语句中断方面的微妙边界情况可能会偏离原生 C 构建。

我们构建 gosuda.org/sqlite3 的目的是让 Go 应用程序无需在 CGO_ENABLED=0 和真正的 C SQLite 引擎之间做出选择。通过将官方的 SQLite 3.54.1 C 合并代码编译到专用的共享内存服务器 (hqq-sqlite-server) 中并通过 gosuda.org/sqlite3 进行通信，您的 Go 二进制文件在编译时带有 CGO_ENABLED=0，同时能够在跨进程边界执行未经修改的、经过 -O3 优化的 C SQLite。

零配置执行：从 go get 到 sql.Open

在现有的 Go 代码库中替换 github.com/mattn/go-sqlite3 仅需要更改空白导入路径。该驱动程序注册为 "sqlite3"（以及用于显式选择的 "hqq-sqlite"），并接受相同的 DSN 查询字符串：

 1package main
 2
 3import (
 4	"context"
 5	"database/sql"
 6	"fmt"
 7	"log"
 8
 9	_ "gosuda.org/sqlite3"
10)
11
12func main() {
13	dsn := "file:app.db?_journal_mode=WAL&_busy_timeout=5000&_txlock=immediate&_foreign_keys=on"
14	db, err := sql.Open("sqlite3", dsn)
15	if err != nil {
16		log.Fatal(err)
17	}
18	defer db.Close()
19
20	ctx := context.Background()
21	if _, err := db.ExecContext(ctx, `CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT NOT NULL)`); err != nil {
22		log.Fatal(err)
23	}
24	if _, err := db.ExecContext(ctx, `INSERT INTO users (name) VALUES (?)`, "Ada Lovelace"); err != nil {
25		log.Fatal(err)
26	}
27
28	var id int64
29	var name string
30	if err := db.QueryRowContext(ctx, `SELECT id, name FROM users WHERE name = ?`, "Ada Lovelace").Scan(&id, &name); err != nil {
31		log.Fatal(err)
32	}
33	fmt.Printf("user #%d: %s\n", id, name)
34}

内嵌的 SLSA 认证工作进程二进制文件

当听到某个库使用 C 工作进程时，一个自然的问题是：“我必须在我的 Go 程序旁边安装或分发一个单独的 C 二进制文件吗？”

不需要。gosuda.org/sqlite3 直接在带有平台标签的 Go 文件（internal/embedded/embed_<goos>_<goarch>.go）中内嵌了针对全部六个主要目标的预构建 hqq-sqlite-server 二进制文件。由于 Go 的构建约束仅编译与您的目标 GOOS 和 GOARCH 相匹配的文件，因此交叉编译 GOOS=linux GOARCH=arm64 go build 会自动仅内嵌约 1.4 MiB 的 linux/arm64 服务器二进制文件。

当 sql.Open 建立其第一个连接时，autolaunch.go 会将内嵌的二进制文件实例化到用户缓存目录（$XDG_CACHE_HOME/hqq/bin/<sha256>/）中，通过 gosuda.org/hqq/secureexec 验证其加密的 SHA-256 摘要是否与 hashes.go 中固定的 ReleaseHashes 映射相匹配，并使用 --parent-stdin 启动工作进程，以使其生命周期严格绑定到您的 Go 进程。

净室实现的 mattn/go-sqlite3 DSN 兼容性

为了作为一个真正的直接替代品，DSN 解析器（dsn.go）实现了在整个 mattn/go-sqlite3 代码库中使用的连接和 pragma 旋钮的净室复本：

将进程隔离转化为吞吐量优势

初看起来，在单独的进程中运行 SQLite 听起来一定比通过 cgo 在进程内调用 sqlite3_step 更慢。在实践中，一旦查询返回多于单行的数据，情况就会完全相反。

逐行 cgo 调用的隐藏成本

在传统的 cgo SQLite 驱动程序中，database/sql 每次驱动一次迭代单行单列。读取包含 4 列的 1,000 行会触发：

• 1,000 次对 sqlite3_step 的 cgo 调用
• 4,000 次对 sqlite3_column_type 以及 sqlite3_column_int64 / sqlite3_column_text 的 cgo 调用
• Go 调度器与 C 栈之间成千上万次的单独边界跨越

请求流水线与 64 KiB 批次预取

gosuda.org/sqlite3 通过围绕 stmt.go、rows.go 和 sqlite3/server/sqlite3_hooks.c 中的两个机制重新设计线路协议，消除了逐行的边界跨越：

 1Go 客户端 (stmt.go / rows.go)                      C11 工作进程 (sqlite3_hooks.c)
 2-----------------------------                       ----------------------------
 31. 单次传输中的流水线：
 4   ResetAsync + BindValuesAsync
 5   + StmtInfoAsync + FetchRowsAsync(128)  =======>  reset -> bind -> stmt_info ->
 6                                                    循环执行 sqlite3_step() 最多 128 行
 7                                          <=======  批次 1（打包在 64 KiB 插槽中的第 1..128 行）
 82. 立即触发预取：
 9   FetchRowsAsync(128) (批次 2)           =======>  循环执行 sqlite3_step() 处理第 129..256 行
10   当 C 步骤处理批次 2 时，Go 调用方
11   扫描来自批次 1 的第 1..128 行！      <=======  批次 2 在共享内存中准备就绪

1. 单次传输查询流水线 (stmt.go)：当 QueryContext 或 Stmt.QueryContext 运行只读语句时，s.query() 会在一个共享内存传输中异步提交 reset、bind_values、stmt_info（在首次执行时）以及 fetch_rows。所有四项操作都在 C 工作进程上背靠背执行，并在一个往返中返回。
2. 紧凑的 C 批次循环与异步预取 (rows.go)：在 fetch_rows（sqlite3_hooks.c）内部，C 工作进程在一个原生 C 循环中逐步执行 sqlite3_step(stmt)，将最多 FetchSize 行（默认 128 行）直接编码到 64 KiB 的共享内存响应插槽中，直到达到批次限制、插槽满或者发生 SQLITE_DONE。一旦 rows.ingest() 解码了批次 1，它就会在将第一行返回给调用方之前触发针对批次 2 的 FetchRowsAsync。当您的 Go 代码扫描批次 1 时，C 工作进程已经在另一个 CPU 核心上逐步处理批次 2 了。

在 Apple M4（darwin/arm64）上，将 gosuda.org/sqlite3（CGO_ENABLED=0）与 github.com/mattn/go-sqlite3（CGO_ENABLED=1）在同一个 SQLite 数据库上进行对比，展示了批处理和流水线的效果：

取消、路径沙盒与连接池恢复

在隔离的工作进程中运行 SQLite 还增强了驱动程序处理超时、不受信任的 SQL 以及文件系统边界的方式：

• 确定性上下文取消 (conn.go 和 errors.go)：每个驱动程序调用都会武装一个轻量级的 context.AfterFunc 守护程序（cn.guard）。如果调用方的 context.Context 在服务器上运行缓慢的递归查询或锁等待时被取消或其截止时间过期，守护程序就会将连接标记为损坏，终止本地会话链接，并发送带外 Cancel() 帧。C 工作进程立即调用 sqlite3_interrupt(db)，解除对 sqlite3_step 的阻塞，而 Go 驱动程序将产生的 SQLITE_INTERRUPT 状态映射为 context.Canceled 或 context.DeadlineExceeded，并指示 database/sql 替换池中的连接。
• 目录沙盒 (sqlsrv_pathrules.c)：C 工作进程在每次 open_v2 调用时强制执行 --allow-dir 路径规则，解析符号链接并拒绝允许目录之外的相对 .. 遍历。sqlite3_load_extension 和 SQLITE_LIMIT_ATTACHED 默认处于禁用状态，因此 SQL 注入无法逃逸出数据库目录或加载任意共享对象。

仓库布局

该仓库的结构使得顶级包提供直接替代的 database/sql 驱动程序，而 launcher/ 和 sqlite3/ 保持可访问状态以用于高级的自定义服务器部署：

 1gosuda.org/sqlite3
 2├── driver.go / api.go         # database/sql 驱动程序注册 ("sqlite3") 与 Connector API
 3├── dsn.go                     # 净室实现的 mattn/go-sqlite3 DSN 解析器与 pragma 配置
 4├── conn.go / tx.go            # 会话生命周期、上下文守护与事务状态机
 5├── stmt.go / rows.go          # 单次传输请求流水线与 64 KiB 批次预取
 6├── errors.go                  # 强类型的 SQLite 主/扩展错误代码与哨兵匹配
 7├── autolaunch.go / hashes.go  # 零配置内嵌服务器实例化与 SHA-256 固定
 8├── internal/embedded/         # 带有平台标签的 //go:embed 二进制文件 (linux, darwin, windows)
 9├── launcher/                  # 用于自定义服务器部署的可配置进程监督器
10└── sqlite3/                   # 生成的 hqq-bindgen Go 客户端与 C11 SQLite 服务器源码
11    └── server/                # C11 服务器实现 (sqlite3_hooks.c, sqlsrv_policy.c)

入门指南

使用 go get 安装模块并通过 sql.Open("sqlite3", dsn) 打开您的数据库：

1go get gosuda.org/sqlite3@v0.3.3540100

• GitHub 仓库：https://github.com/gosuda/hqq-sqlite3
• DSN 与 Pragma 参考：docs/DSN.md
• 架构与线路协议：docs/ARCHITECTURE.md