PureDb 1.0.0-preview.3

PureDb — 纯 .NET 10 文件数据库

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

当前预览版：1.0.0-preview.3，主库与可选兼容包版本一致。 本版优化计划缓存、解码、JSON 派生表达式和检查点，并扩展纯托管 SQLite 文件格式支持。SQL、文件协议和事务能力有明确边界；当前没有在所有性能、CPU、内存指标上超过 SQLite。

SQL 支持与不支持清单 · 安装与使用 · ADO.NET · SQLite 文件兼容 · 全面性能表 · CPU / 内存谁更高 · 可筛选性能面板 · 原始结果 · 自动发布

主分支已包含 复合索引、外键、CHECK、UPSERT、视图、行触发器、CTE、窗口、相关子查询、集合运算、JSON5 / JSON 表函数、SQL 事务和保存点，以及 C# 用户函数、查询快路径和中文注释。各项限制、示例和未支持语法集中见 SQL 清单。下面的功能矩阵对应 main 源码；全面性能表已使用本轮冻结的 preview.3 构建在 Windows 和 Linux ARM64 完整重测，另有 排序专项报告 和 本轮优化前后对照 和 AOT 完整报告。开发验证 与 扩展进度 记录实际验证和剩余工作。

安装

安装已发布的 NuGet 版本：

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

也可从 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)。

preview.3 支持将 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-preview.3 预览版 / SQLite 3.54.1。✅ 已实现，⚠️ 有限制或需额外组件，❌ 尚未实现。功能标记表示支持范围，不表示相同的实现、成熟度或性能。

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

本轮优化与兼容性验收

固定 19 项读取/重开使用同一宿主仅替换内核，与 SQLite 串行轮换三轮；没有剔除退化项。精确前后收益见 优化报告。完整 41 项及 CPU/RSS 分开报告；性能仍没有全面超过 SQLite。

SQL 固定公开语料 175 条、SQLite 文件正向 profile 与崩溃恢复 64 组，Windows x64 和 Linux ARM64 分别验证。分母、通过率和未覆盖能力见 兼容性报告；这不是整体 SQLite 兼容性 95% 的声明。文件模式性能单独见 兼容后端专项。

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

Native AOT 发布对比

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

主分支 preview.3 排序专项

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

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

主分支 preview.3 与 SQLite 全面对比

下方完整对比对应本轮 preview.3 发布构建。 Windows 与 Linux ARM64 使用同一份 DLL；旧的全面对比记录已替换。本轮优化的收益与仍落后项目见 优化报告。

1.0.0-preview.3 本轮发布构建原生格式 vs SQLite 3.54.1，同机三轮中位数。CPU 为满吞吐进程占用，内存为单库独立测量。使用率高不代表每次查询更费 CPU。以下是代表场景，全部 41 项、ADO、CPU 和文件数据见完整报告。

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

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