PureDb.SqliteCompatibility 1.0.0-rc.1

PureDb — 纯 .NET 10 文件数据库

PureDb 使用 C# 和 .NET 10 标准库实现嵌入式数据库，提供 KV、SQL、JOIN、JSON、事务、多线程写入、多进程访问和 ADO.NET。核心与可选 SQLite 文件兼容库均无原生库和第三方 NuGet 依赖。

当前候选版：1.0.0-rc.1，主库与可选兼容包版本一致。 本版重点处理大库主键范围、检查点内存回收、半开区间增删改、压缩关闭与一致快照备份，并修复大整数、IS 和位运算兼容性。当前没有在所有性能、CPU、内存指标上超过 SQLite，也不以候选版标签替代生产验证。

SQL 支持与不支持清单 · 安装与使用 · ADO.NET · SQLite 文件兼容 · 当前 41 项与 CPU / RSS · 十万 / 百万行及文件大小 · 正式发布评估 · 当前原始结果 · 自动发布

主分支已包含 复合索引、外键、CHECK、UPSERT、视图、行触发器、CTE、窗口、相关子查询、集合运算、JSON5 / JSON 表函数、SQL 事务和保存点，以及 C# 用户函数和中文 XML 注释。边界见 SQL 清单。当前 41 项及十万 / 百万行对照均使用同一冻结 DLL 在 Windows x64、Linux ARM64 重测；已有排序和 AOT 部署体积专项明确保留 preview.3 版本标签。

安装

安装已发布的 NuGet 版本：

dotnet add package PureDb --version 1.0.0-rc.1
# 需要原地读取/修改受支持的 SQLite 文件时额外安装：
dotnet add package PureDb.SqliteCompatibility --version 1.0.0-rc.1

也可从 main 构建源码；构建及本地打包命令见文末。两个包的版本统一由 Directory.Build.props 定义，变更见 CHANGELOG。

using PureDb;

await using var db = new SqlDatabase("app.pdb");
await db.ExecuteAsync("CREATE TABLE IF NOT EXISTS users(id INTEGER PRIMARY KEY,name TEXT NOT NULL,profile JSON)");
await db.ExecuteAsync("INSERT INTO users VALUES(@id,@name,@profile)",
    new Dictionary<string, object?>
    {
        ["id"] = 1L, ["name"] = "小明", ["profile"] = "{\"age\":25}"
    });
var result = db.Query("SELECT name,json_extract(profile,'$.age') AS age FROM users WHERE id=@id",
    new Dictionary<string, object?> { ["id"] = 1L });
Console.WriteLine(result.Rows[0][0]);

KV 使用 Database，SQL 使用 SqlDatabase，各自使用独立文件。SQL 表需要 INTEGER PRIMARY KEY，主键范围 [0, 2^40)。

可以将 C# 方法注册为 SQL 标量函数，SqlDatabase 和 ADO.NET 连接都提供相同入口：

db.CreateFunction<string?, bool>("RELIGIBLE", user => user is "Alice" or "小明");
var eligible = db.Query("SELECT * FROM users WHERE RELIGIBLE(name)");

函数按连接、名称和参数数量注册，可替换或移除。强类型入口直接调用委托，布尔结果复用 SQL 0/1 对象，省去逐行参数数组和布尔装箱；NULL、BLOB 复制和业务异常仍经过边界检查。使用方法及限制见 用户函数。

与 SQLite 功能对比

基准：PureDb 1.0.0-rc.1 候选版 / SQLite 3.54.1。✅ 已实现，⚠️ 有限制或需额外组件，❌ 尚未实现。功能标记表示支持范围，不表示相同的实现、成熟度或性能。

SQLite 能力依据官方 SQL 文档、自定义函数、JSON 文档、WAL 文档；其 .NET 提供程序见 Microsoft.Data.Sqlite。PureDb 的逐类语法、例子、原理和限制见 SQL 支持清单。

本轮优化与兼容性验收

原生主键范围不再先扫描全表或创建重复索引；检查点流式写入并释放已持久增量，半开区间同时利用上下界。压缩、关闭、首次查询与热查询分开计时；全部改善及退步见 十万 / 百万行报告。

Windows x64 与 Linux ARM64 分别通过 SQL 固定公开语料 175 条、扩展差分 298 条及 SQLite 文件正向与恢复 66 组，并完成各 100 万次随机变更、并发读取、维护强杀和 AOT 验证。Linux 另通过真实部分写入错误恢复。分母与未覆盖能力见 发布就绪评估；这不是整体 SQLite 兼容性 95% 的声明。

博客园独立文章：实现原理、功能对照、真实性能图与限制。

preview.3 的 AOT 部署体积参考

rc.1 已重新编译运行 AOT 功能与差分测试，详见发布评估；下表是此前 preview.3 应用宿主的部署体积，保留原版本边界，不作为 rc.1 体积测量。

SQLite 体积包含其原生库；AOT 体积是本次应用发布闭包。详细 CPU、RSS、增删改及方法见 AOT 完整报告。

preview.3 排序专项（历史测量）

10 万行热缓存排序，三轮中位数；数值越低越好。此表对应冻结的 preview.3 发布源码，CPU 是每次查询消耗的时间。

托管分配相对优化前的变化、全部四个场景及方法见 排序专项报告。分配减少不等于 RSS 降低；此专项不代表全部 SQL 已超过 SQLite。

当前 rc.1 与 SQLite 全面对比

下方为当前候选版的真实对照；历史 preview.3 的性能、排序和 AOT 记录保留其原版本标记，不混用为 rc.1 测量。

1.0.0-rc.1 当前冻结原生内核 vs SQLite 3.54.1，同机三轮中位数，差距不足 5% 标为接近。下表包括仍落后的项目，完整 41 项、CPU、RSS、ADO.NET 见 当前报告，百万行与文件大小见 规模报告。

Windows x64

Linux ARM64

🟩 PureDb 更低，🟥 SQLite 更低，🟨 差距小于 5%。耗时、CPU 时间、驻留内存分别评判。 KV 对 SQL、纯 SQL 对 SQL、ADO.NET 对 SQLite C API 的接口差异在报告中单独说明。热缓存与重复聚合的优势不能外推到所有业务。

原理、实现思路与技术

1. 分层：SQL 与存储引擎解耦

flowchart TD
  A[SQL / ADO.NET] --> B[解析 AST 与参数绑定]
  B --> C[执行计划缓存 / 专用查询路径]
  C --> D[ISqlStorage]
  K[KV API] --> E[PureDb 原生存储]
  D --> E
  D -. 可选兼容包 .-> S[SQLite B-tree / 回滚日志后端]
  E --> W[写入队列与事务提交]
  W --> L[追加日志与 CRC32]
  E --> I[分页检查点与整数索引]
  E --> P[数据页与热点缓存]

核心项目包含原生存储、SQL 和 ADO.NET。PureDb.SqliteCompatibility 单向依赖核心，实现同一存储抽象，核心不依赖兼容库。默认创建的是 PureDb 文件；只有显式使用兼容入口才处理 SQLite 文件。

2. 存储：追加日志、校验与分页检查点

提交将变更编码为事务帧，记录长度、长度反码、CRC32 和操作列表，顺序追加到日志。值留在磁盘，主键索引保存值的位置、长度及校验信息。追加设计减少原地随机修改，但会累积旧版本，需要压缩回收。

主索引由分页持久化检查点、内存增量与有界热点页组成。有效检查点存在时，打开只读元数据，再恢复检查点之后的日志尾部；检查点缺失或失效则扫描重建。数据库变大不要求每次都加载全部数据，但恢复尾部、重建和完整校验仍可能与数据量相关。整数 SQL 索引也以页为单位延迟读取。

默认按访问验证索引页和数据值的 CRC。覆盖索引只访问索引时，不会同时扫描未请求的数据负载；VerifyOnOpen / VerifyIntegrity 用于完整校验。校验和用于发现损坏，不等同于纠错。

源码：原生引擎、主索引与检查点、分页索引。

3. 写入：有界队列、批量事务与分组提交

Full 写入通过 Channel 有界队列进入单写入者，合并一组请求的日志写入与刷盘，分别保留事务边界，并在确认前完成刷盘。一个批次包含多条变更时，共享编码、提交和同步成本。Buffered SQL 可以在调用线程提交，减少队列往返，但它和 SQLite WAL/NORMAL 的 checkpoint、关闭及断电行为不同。

ReaderWriterLockSlim 协调实例内访问；Shared 模式使用命名 Mutex、协调戳内存映射及日志追赶处理多进程更新。协调戳是缓存提示，日志与代际校验才是恢复依据。写入仍然串行，更多线程不保证线性加速。

源码：写入与恢复、SQL 事务。

4. 查询：识别常见形状，减少通用执行开销

SQL 先解析成 AST，再缓存参数绑定、列投影和受支持的执行计划。主键查询直接定位记录；只投影主键时可使用覆盖索引。整数范围查询以精确二分为基础，增加经过实际键验证的估算探测；偏斜或不适合的分布保留精确查找。小 LIMIT 验证最后候选键后，减少另一端边界搜索和读页。

区间 UPDATE / DELETE 直接读取目标范围，避免先解码整表；没有 UNIQUE 约束时省去约束集合。通用谓词和不支持的优化形状走通用执行器，不能把专用路径的倍率当作所有 SQL 的速度。

主分支持续使用小分页排序：输入未满足 ORDER BY、无分组及 DISTINCT、OFFSET + LIMIT <= 4096 时，用 PriorityQueue 保留最好的 K 行，堆顶始终是最差候选。纯列查询只保留输入行引用，入选后再生成结果投影；含表达式时，淘汰候选的投影与键数组作为下一行缓冲区复用。排序候选的保留空间从随 N 行增长降到随 K 行增长；比较工作为 O(N log K)，已命中索引顺序的查询继续直接分页。

比较器复用 SQL 的 NULL、整数/实数、文本和 BLOB 规则，整数对整数先直接比较，省去 JSON 解包和存储类别判断，并以原始输入序号保持相同键的稳定顺序。含表达式的查询仍逐行执行投影，ORDER BY 别名复用投影值，易变 C# 函数每行调用次数及未入选行异常保持一致。大分页、分组、去重回退到原执行器；表缓存、函数结果和最终输出仍有额外内存，O(K) 只描述排序候选缓冲区。

源码：查询分派、有界排序、范围查询、区间 DML。

5. JOIN、聚合、JSON 与 SIMD

等值 JOIN 可使用缓存哈希查找及直接投影，其他形状保留通用循环。无过滤 COUNT 使用维护的精确计数；分组计数可复用按数据版本生成的统计与排序结果。写入后会失效或重建，缓存有内存和首次建立成本。

JSON 路径及解析结果可复用；整数派生列采用连续数组，对受支持的“正的 2 次幂取余等于零”计数使用 System.Numerics.Vector<long> 位运算，保留 NULL 和负数语义。其他条件走标量或通用路径。CRC32 同样有硬件/向量路径与回退。硬件通道数不等于实测加速倍率。

PureDb 在部分用例比 SQLite 快，主要来自这些专用路径、版本化缓存和减少物化工作；SQLite 也使用索引和字节码执行。本项目同时保存参测 SQLite 的 EXPLAIN 计划，避免把优势误解成“SQLite 没有索引”。

源码：JOIN、聚合、SIMD 计数、JSON、CRC。

6. 内存、ADO.NET 和兼容模式的边界

数据页缓存默认 64 MiB，SQL 行缓存另有 64 MiB 估算预算，索引、执行计划、结果和运行时还有额外占用，不能把缓存预算当成进程内存上限。BLOB 返回独立副本；数据和模式版本决定缓存何时失效。当前内存占用仍有弱于 SQLite 的场景。

ADO.NET 提供 Connection、Command、Parameter、DataReader、DbTransaction 和 ProviderFactory。事务使用带冲突检测的乐观 Serializable；调用方需要处理冲突重试。ADO.NET 兼容不等于已兼容所有 ORM 及完整 SQLite SQL。

兼容包实现 SQLite B-tree 页、record 编码、overflow 和回滚日志子集；仅允许声明的格式及独占使用方式。默认写入可能重建整库，实验增量更新只覆盖特定页内修改，其他情况回退。WAL、未知模式和未实现协议明确拒绝。详细限制见 兼容文档。

构建、验证与复现

需要 .NET SDK 10.0.402。核心无第三方包，NuGet.Config 可离线恢复。SQLite 原生库仅用于测试和对比，不进入发布包。

dotnet build PureDb.slnx -c Release
dotnet pack src/PureDb -c Release --no-build -o artifacts/packages
dotnet pack src/PureDb.SqliteCompatibility -c Release --no-build -o artifacts/packages
python scripts/prepare-sqlite.py
python scripts/test.py
# 小分页排序专项，与 SQLite 核对结果后测量耗时、CPU 时间和托管分配：
dotnet run -c Release --no-build --project tests/PureDb.SortTests -- --measure
# 创建 10 万行数据集，然后以程序输出的目录运行：
dotnet run -c Release --no-build --project benchmarks/PureDb.QueryBenchmarks -- 100000 1
python scripts/run-benchmarks.py artifacts/new-comparison DATASET --tests --memory --ado

CI 在 Windows / Linux 上构建并运行回归和 SQLite 差分查询，检查中文源码文档、格式及实际 NuGet 包。性能测量按主机串行进行；仓库分别保留 完整预览版对比、用户函数专项 和 本次排序优化前后 的最新证据，不保存测试数据库或运行库二进制。复现细节见 基准方法。

preview.3 的实现调整

已解析语法树不可变，计划缓存改用 AST 对象身份及表/模式上下文键，省去重复 record 递归哈希。小整数装箱复用不可变对象；全列顺序投影直接顺序解码，重排/重复列回退原路径，BLOB 仍复制。JSON 派生计数弱缓存规范化表达式，只减少表达式树重建，数据按版本失效、参数和计数仍实际求值。

检查点直接归并已有排序索引和新增部分，避免全量主键重新排序；计数使用单次字典定位。CRC、边界、刷盘顺序和 Shared 故障恢复没有放宽。已有 ARM CRC32 和 JSON SIMD 已存在于基线，本轮没有把它们再次计为新增优化。

密集 KV 主键的热点页通过有界数组目录直接定位，省去重复散列；目录按行数及预算分配，稀疏高位键保留字典路径。相同编码的查询不反复写线程状态，跨编码嵌套用户函数仍保存和恢复上下文。并发初始化、目录边界、写后失效、压缩及重开均有验证。

兼容包保留 SQLite 页尺寸与文本编码，按编码执行 BINARY 排序和文本/BLOB 转换。模式渲染器保存复合索引方向、DEFAULT、CHECK、外键、视图与触发器。完整镜像回退仅备份实际覆盖和截断的旧页，但镜像构建仍随库大小增长；实验增量路径不覆盖任意 SQL。更多原理见 优化报告 和 文件协议边界。

自动发布与许可

main 当前版本为 1.0.0-rc.1。合并或推送主分支会运行 CI；发布对应的 v1.0.0-rc.1 标签后，发布流水线 才会校验版本、执行 Windows / Linux 测试、打包两个纯 .NET 包、发布至 NuGet 并创建 GitHub 候选版发布。仓库需要配置 Actions Secret NUGET_API_KEY；失败的任务会停止后续发布。NuGet 的两个包独立接收上传，跨包发布不具有原子性。详见 发布说明。

项目采用 MIT。CRC 向量实现的来源和版权声明见 第三方声明。