SonnetDB Help Center
仓库

SonnetDB Docs

SonnetDB 3.0.0 Release Notes

SonnetDB 3.0.0 相对 v2.5.0 的发布变更说明。

SonnetDB 3.0.0

本说明覆盖从上一版 GitHub Release v2.5.0 到本次发布版本 v3.0.0 的变更范围（自 v2.5.0 起 100+ 次提交）。这是一个里程碑级大版本：完成 M28 跨子系统审计整改的全部收官，并新增覆盖全部七个数据模型的高吞吐二进制接入通道与设备直连能力。

Highlights

  • 全新二进制帧协议（HTTP/2）：新增覆盖 MQ / 时序 / SQL / 向量 / KV / 对象 / 文档全部七个 service 的长度定界二进制帧协议，消灭 JSON/Base64 税——列式时序写 wire 体积约为 JSON 的 1/3.7、编码约 300× 快且零 LOH，向量检索请求编码约 1000× 快。所有既有 REST/JSON 端点保留，帧层为纯增量、不改任何引擎语义。
  • MQTT 设备直连：新增单机内建 MQTT broker（设备 PUBLISH db/{db}/m/{measurement} 直接落库、SUBSCRIBE 推送 SonnetMQ）与订阅外部 broker（EMQX/Mosquitto）的 MQTT client，两者复用同一套三格式摄取与三角色鉴权。
  • PostgreSQL 风格远程连接：ADO.NET 连接串支持 Host/Port/Username/Password/Ssl，服务端支持 HTTP Basic 认证与 SONNETDB_USER/PASSWORD/DB 容器首启引导（对标 postgres entrypoint）。
  • 可观测性基线：SonnetDB.Core 引入零第三方依赖的 Meter/ActivitySource 插桩（写入/WAL fsync/flush/compaction/查询/段读/per-db gauge），Server 侧接入 OpenTelemetry 与可选 /metrics Prometheus 端点，Web Admin 新增内嵌监控面板。
  • M28 审计整改全部收官：54 项跨子系统缺陷（存储 S# / 索引 I# / SQL Q# / 并发 C#）按「先止血 → 再正确 → 再吞吐 → 再能力」分阶段全部修复——涵盖掉电/崩溃数据可靠性、SQL 三值逻辑与关系语义、写路径吞吐、查询流式合并、向量索引度量贯通与 HNSW 回收、SonnetMQ 去全局锁/组提交/冷数据下沉等。
  • 文档模型能力升级：Document Store 补齐查询规划器与代价模型、聚合管线子集、局部更新操作符、cursor 分页、复合/unique/sparse/TTL/partial 索引、collection validator、单文档原子性与批量写轻事务，并新增持久化文档向量（ANN）索引。
  • 连接器矩阵扩展：C ABI 连接器新增 bulk ingest / KV / Document / Object / MQ 分组，Go / Rust / Java / Python 上层连接器同步补齐 idiomatic 包装；新增 Testcontainers.SonnetDB 集成测试模块。

Frame Protocol（高吞吐二进制接入）

  • 固定 12 字节小端帧头（payloadLen ≤ 132 MiB 先于分配校验 | version | service | op | flags | streamId），基元 varuint/varstr/bytes，FrameCodec.TryReadFrame 基于 ReadOnlySequence 增量解析。
  • 服务端新增一元端点 POST /v1/frame（逐帧处理逐帧回帧，内存上界=单帧）与双工流端点 POST /v1/frame/stream（HTTP/2 长流服务端推送，MQ 订阅从轮询升级为推送）；新增 h2c 监听口（明文 HTTP/2）。
  • 错误模型：未成帧走 HTTP 400/415/401，成帧后一切按帧回错误帧（HTTP 200，错误码复用 REST 词汇），批内单帧失败互不影响。
  • 客户端 SonnetDB.Data 远程模式接入帧协议：连接串 Protocol 选项（auto 探测 / frame-http2 强制 / rest 强制），MQ / KV / 文档 / 对象 / 时序批量写 / 只读 ADO SQL 数据面优先走帧、其余回落 REST。

兼容性提示（已记录）：在默认 Protocol=auto 下，ADO SQL 走帧路径时对部分列返回更富的 CLR 类型（时间戳 DateTime、blob byte[]、向量 float[]、整数值 double 不再折为 long），而旧 REST NDJSON 路径返回字符串。消费 SndbDataReader.GetValue / GetFieldType 的既有代码需知悉此差异；如需保留旧字符串类型行为，可在连接串显式设置 Protocol=rest。MQ / KV / 文档三者两条传输字节一致，无此差异。

MQTT 设备接入

  • 内建 broker（SonnetDBServer:Mqtt）：基于 MQTTnet.AspNetCore.Routing，默认 TCP 1883 + WebSocket /mqtt；db/{db}/m/{measurement} PUBLISH 复用 BulkIngestEndpointHandler 三格式落库（Line Protocol / JSON points / BulkValues），db/{db}/mq/{topic} 写入 SonnetMQ；QoS 0/1、精确 topic、单节点范围。
  • 外部 client（SonnetDBServer:Mqtt:ExternalClient）：订阅既有 EMQX/Mosquitto，收到 db/{db}/m/{measurement} 消息复用同一摄取管线落库，支持 TLS、外部凭据、topic filter 列表与指数退避重连；可独立或与内建 broker 同时运行。
  • Core 保持零第三方运行时依赖；MQTT 依赖仅在 Server 程序集。

Observability

  • Core：SonnetDB.Diagnostics 命名空间，Meter("SonnetDB.Core") + ActivitySource("SonnetDB.Core")，插桩写入吞吐/时延、WAL fsync、flush、compaction、查询、段物理读与 4 个 per-db ObservableGauge；热路径经 Instrument.Enabled 短路，无监听者时零开销。
  • Server：OpenTelemetry.Extensions.Hosting + AspNetCore/HttpClient instrumentation，OTLP 导出仅在设置 OTEL_EXPORTER_OTLP_ENDPOINT 时挂接；Observability:Prometheus:Enabled=true 时 /metrics 由 Prometheus exporter 接管。
  • Web Admin：新增「监控」侧边栏（/admin/app/monitoring），纯前端解析 prom exposition 绘制写入吞吐/查询 P95/WAL fsync P95/MemTable 占用等内联 SVG 折线。

Relational / SQL

  • ALTER TABLE ... ADD FOREIGN KEY（追加时校验存量数据、失败回滚）与 ON DELETE CASCADE / SET NULL / NO ACTION 语义。
  • 关系语义补齐：SELECT DISTINCT、大小写策略统一、值定向 DELETE、聚合类型静态推断；时序 WHERE 支持字段谓词与顶层 OR（三值 Kleene）。
  • 性能：SqlParser.Parse 解析缓存、参数化查询/绑定变量、ORDER BY ... LIMIT 有界 Top-N、等值哈希连接、非相关子查询记忆化、大范围点查询流式合并。
  • EF Core provider 集成完善（设计期服务、dotnet ef 工具链）与 IoTSharp 实际查询形状适配（多列排序、拆分查询排序、IS/IN 谓词、子查询投影列名、遥测 INSERT 类型推断、Guid 值生成、远程迁移历史检测与幂等 DDL 迁移）。

Packaging

发布脚本会生成以下 NuGet 包（版本号由 CI/tag 注入）：

  • SonnetDB.Core（已并入 SonnetMQ 消息队列，不再单独发布 SonnetMQ 包）
  • SonnetDB
  • SonnetDB.EntityFrameworkCore
  • SonnetDB.Caching.EasyCaching
  • SonnetDB.Caching.Distributed
  • SonnetDB.Cli
  • Testcontainers.SonnetDB（Testcontainers for .NET 模块，供下游在集成测试中一键拉起临时 SonnetDB Server 容器）

安装命令不固定版本号：

dotnet add package SonnetDB.Core
dotnet add package SonnetDB
dotnet add package SonnetDB.EntityFrameworkCore
dotnet tool install --global SonnetDB.Cli

Compatibility Notes

  • 目标框架仍为 .NET 10 / net10.0。
  • 所有既有 REST/JSON 端点与嵌入式路径保留；帧协议与 MQTT 均为增量接入，不改任何引擎读写/查询/索引/存储语义。
  • 唯一记录在案的行为差异：Protocol=auto 下 ADO SQL 帧路径的富 CLR 类型（见上文 Frame Protocol 兼容性提示）；如需旧行为设置 Protocol=rest。
  • VersionPrefix 保留为开发默认值；实际 NuGet 版本由 CI/tag 发布时注入。
  • 磁盘格式：段文件与 WAL 二进制布局向后兼容（旧段可读）；measurement schema 与段内向量索引 section 已升版并对旧版本做默认值兼容读取。

Verification

本地发布前建议执行：

dotnet restore SonnetDB.slnx
dotnet build SonnetDB.slnx --configuration Release --no-restore /warnaserror
dotnet test SonnetDB.slnx --configuration Release --no-build
.\eng\release.ps1 -Tasks nuget -Version 3.0.0

生成的 NuGet 包位于 artifacts/release/nuget/。