SonnetDB

中文 | English

🚀 SonnetDB 是什么

SonnetDB 是一个基于 C# / .NET 的多模型数据库。它用一套本地引擎、一套 SQL / API 和一个 Web Admin，同时提供：

能力	用来做什么
时序数据库	设备指标、工业采集、日志指标、时间窗口聚合、压缩、Retention
关系型数据库	业务表、维表、配置表、主键、索引、JOIN、事务、EF Core
KV / 缓存	设备状态、会话、配置、TTL、前缀扫描、缓存 Provider
JSON 文档	文档集合、JSON path、文档查询、文档索引
全文 + 向量搜索	BM25、向量 KNN、Hybrid Search、知识检索
对象存储	S3-compatible bucket、分片上传、Range 读取、Presigned URL
消息队列	SonnetMQ topic、consumer group、pull / ack、重启 replay
AI Copilot	SQL 生成、解释、修复、排障、知识引用、写入审批

使用方式	入口
嵌入式	Tsdb.Open(...) 直接在进程内打开数据库目录
服务端	Docker / HTTP API / /admin/ / /help/
.NET 生态	ADO.NET、EF Core、IDistributedCache Provider
命令行	sndb 本地 / 远程执行 SQL、备份和维护
多语言	C、Go、Rust、Java、Python、VB6、PureBasic 连接器
AI / Agent	Web CopilotDock、MCP 工具入口

🏷️ 生态下载与版本

📦 NuGet

🐳 Docker

🔌 连接器与下载入口

✨ 核心特点

• 一个部署，多种数据能力：时序、关系、KV、文档、搜索、对象、消息队列和 Copilot 在同一个产品里协同。
• 嵌入式 + 服务端双形态：可以嵌入应用，也可以作为 HTTP 服务运行。
• SQL 优先：写入、查询、聚合、JOIN、全文、向量、权限和管理操作都尽量收敛到 SQL / API。
• 开箱即用的控制面：内置用户、授权、Token、备份恢复、事件流、指标、Admin UI、Workbench 和 Copilot。
• 面向工程落地：提供 NuGet、Docker、CLI、ADO.NET、EF Core、多语言连接器和 MCP 工具入口。

🌐 官网与资源

入口	地址
官方主页	https://sonnetdb.com
在线文档	https://sonnetdb.com/docs
开源仓库	https://github.com/IoTSharp/SonnetDB
企业版与云平台	https://sonnetdb.com/platform

💬 交流社群

欢迎扫码加入企业微信群，交流 SonnetDB 使用、开发和落地问题。

当前组成

组件	说明
src/SonnetDB.Core	多模型核心库，包含时序、关系表、KV、文档、搜索、对象存储适配、备份恢复和底层持久化能力
src/SonnetDB	HTTP 服务端、首次安装流程、认证授权、SSE、MCP、Admin UI、Copilot 桥接和内置 /help 文档站点
src/SonnetDB.Data	ADO.NET 提供程序，NuGet 包名为 SonnetDB，命名空间为 SonnetDB.Data
src/SonnetDB.EntityFrameworkCore	EF Core Provider，NuGet 包名为 SonnetDB.EntityFrameworkCore，提供 UseSonnetDB(...)、类型映射、查询翻译和 migrations SQL
src/SonnetDB.Cli	命令行工具 sndb：本地/远程连接、profile 管理（local/remote/connect）、交互式 REPL
src/SonnetMQ	零依赖本地消息队列核心库，提供 topic publish、consumer group pull/ack 和重启 replay
extensions/SonnetDB.Caching	基于 SonnetDB KV keyspace 的缓存 Provider，可用于 IoTSharp / EasyCaching / IDistributedCache 场景
web	管理后台前端（包含 SonnetDB Workbench、全局 CopilotDock 与 SPA 发布静态资源）
docs	JekyllNet 文档站点源码；构建镜像时会生成并打包到 /help

快速开始

1. 嵌入式最小示例

using SonnetDB.Engine;
using SonnetDB.Sql.Execution;

using var db = Tsdb.Open(new TsdbOptions
{
    RootDirectory = "./demo-data",
});

SqlExecutor.Execute(db, """
CREATE MEASUREMENT cpu (
    host TAG,
    usage FIELD FLOAT
)
""");

SqlExecutor.Execute(db, """
INSERT INTO cpu (time, host, usage)
VALUES (1713676800000, 'server-01', 0.71)
""");

var result = (SelectExecutionResult)SqlExecutor.Execute(
    db,
    "SELECT time, host, usage FROM cpu WHERE host = 'server-01'")!;

foreach (var row in result.Rows)
{
    Console.WriteLine($"{row[0]} {row[1]} {row[2]}");
}

2. 启动服务端

docker build -f src/SonnetDB/Dockerfile -t sonnetdb .
docker run --rm -p 5080:5080 -v ./sonnetdb-data:/data sonnetdb

仓库的 Docker 发布工作流会额外构建并推送预编译镜像 iotsharp/sonnetdb 与 ghcr.io/<owner>/sonnetdb。当仓库 Secrets 配置完成后，也可以直接拉取：

docker run --rm -p 5080:5080 -v ./sonnetdb-data:/data iotsharp/sonnetdb:latest

启动后访问：

• http://127.0.0.1:5080/admin/
• http://127.0.0.1:5080/help/

当 /data/.system 为空时，/admin/ 会进入首次安装流程，要求设置：

• 服务器 ID
• 组织名称
• 管理员用户名
• 管理员密码
• 初始静态 Bearer Token

3. 通过 ADO.NET 访问

using SonnetDB.Data;

using var connection = new SndbConnection("Data Source=./demo-data");
connection.Open();

using var command = connection.CreateCommand();
command.CommandText = "SELECT count(*) FROM cpu";

var count = (long)(command.ExecuteScalar() ?? 0L);
Console.WriteLine(count);

远程连接示例：

using SonnetDB.Data;

using var connection = new SndbConnection(
    "Data Source=sonnetdb+http://127.0.0.1:5080/metrics;Token=your-token");
connection.Open();

4. 通过 CLI 访问

# 安装
dotnet tool install --global SonnetDB.Cli --version 0.1.0

# 本地直接使用
sndb local --path ./demo-data --command "SELECT count(*) FROM cpu"

# 保存 profile，下次免输路径
sndb local --path ./demo-data --save-profile home --default
sndb connect home --command "SELECT count(*) FROM cpu"

# 连接远程服务端
sndb remote --url http://127.0.0.1:5080 --database metrics --token your-token --repl

更完整的 CLI、ADO.NET、嵌入式、远程和批量写入示例见 docs。 Web Admin Workbench（Schema Explorer / SQL Editor / Staged Preview / Result Grid / Trajectory 模式）说明见 docs/web-workbench.md。

深入文档

README 只保留项目概览和最短入门路径，完整说明放在专题文档中：

主题	文档
入门、部署、首次安装	开始使用
时序建模、measurement / tag / field / time	数据模型
SQL 语法、函数、控制面 SQL	SQL 参考、SQL Cookbook
Web Admin、SQL 工作台、Copilot	SonnetDB Workbench
嵌入式 API、ADO.NET、EF Core、CLI	嵌入式 API、ADO.NET、CLI
批量写入、Line Protocol、JSON ingest	批量写入
KV、文档、全文、向量、Hybrid Search	KV Keyspace、向量搜索
地理空间、轨迹、预测、PID	地理空间、预测、PID 控制
架构、目录布局、备份恢复	架构总览、文件格式、备份恢复
发布产物、Docker、安装包	发布与打包
性能与可靠性	基准说明、近期性能与可靠性变更

基准与可靠性

同机基准和复现实验请以 tests/SonnetDB.Benchmarks/README.md 为准。README 只保留结论入口：

• Server-vs-Server 写入对比中，SonnetDB Server 在同机测试下约为 IoTDB 的 1.98x。
• 批量写入、范围查询、时间窗口聚合、向量召回和地理空间查询都有独立 benchmark。
• WAL、Segment、Compaction、Retention、备份恢复和索引生命周期的近期变更见 性能与可靠性近期变更。

Parity vs Open-Source Stack

SonnetDB 的多模型能力通过独立 parity 套件持续和开源组件对齐：PostgreSQL、InfluxDB、VictoriaMetrics、Redis、Qdrant、MinIO、NATS JetStream、Meilisearch 和 ClickHouse。.github/workflows/parity.yml 每日 02:00 UTC 运行 light / full 两档矩阵，能力、可靠性和算法准确度作为红绿门槛，性能数字只进入 warning/report。

最新 nightly 结果发布到 parity-results 孤立分支；可读样例见 tests/SonnetDB.Parity/reports/sample-run.md，路线说明见 docs/parity-roadmap.md。

设计原则

• 核心库 safe-only，不使用 unsafe。
• 一个数据库目录承载持久化数据，不再以单文件数据库作为产品描述。
• 嵌入式和服务端共享 SQL / API 语义。
• 管理能力内置到 Server、Web Admin、CLI 和 Copilot 中。

相关文件

• 路线图见 ROADMAP.md
• 变更记录见 CHANGELOG.md
• AI 协作规范见 AGENTS.md

License

MIT