FreeSql 的 SonnetDB Provider 已经合并到上游,接入时可以继续使用 FreeSql 的熟悉入口,同时把 SonnetDB 的关系表和时序 measurement 分开处理。本文从连接、实体标记和 CodeFirst 开始,再说明 CRUD、事务、锁定读和边界。源码接入事实见 IoTSharp/FreeSql master 提交;上游合并见 FreeSql PR #2234。
连接和模型选择
Provider README 给出的连接形状是:
using FreeSql;
using FreeSql.DataAnnotations;
using FreeSql.Provider.SonnetDB.Attributes;
using var fsql = new FreeSqlBuilder()
.UseConnectionString(DataType.SonnetDB, "Data Source=./sonnet-data")
.UseAutoSyncStructure(true)
.Build();
带有 [SonnetDBTable] 的实体走关系表映射;未标记的实体继续使用 measurement 映射。这个标记不是装饰性的命名约定,而是告诉 Provider 当前模型应该使用哪一套 SQL 和类型边界。

图1:从实体模型进入 CodeFirst、参数化 CRUD、事务和锁定读的流程。AI 主题示意图,并非可复制代码截图。
关系表 CodeFirst 和 CRUD
一个最小关系实体可以这样写:
[SonnetDBTable]
[Table(Name = "devices")]
public sealed class Device
{
[Column(IsPrimary = true, IsIdentity = true)]
public long Id { get; set; }
public string Name { get; set; } = string.Empty;
[Column(IsVersion = true)]
public long Version { get; set; }
}
随后可以继续使用 FreeSql 的实体写入和查询入口:
var device = new Device { Name = "pump-01" };
device.Id = fsql.Insert(device).ExecuteIdentity();
var loaded = fsql.Select<Device>()
.Where(a => a.Id == device.Id)
.ToOne();
loaded.Name = "pump-02";
fsql.Update<Device>()
.SetSource(loaded)
.ExecuteAffrows();
ROWVERSION 由 SonnetDB 生成,Provider 保留 FreeSql 的旧版本匹配和 DbUpdateVersionException 行为。示例只说明源码接口形状,不把当前页面变成正式包消费者证明。
DbFirst、索引和锁定读
DbFirst 的关系实体需要保留关系表标记,并按实际数据库结构读取主键、自增、普通/唯一索引和已支持的表列迁移。锁定读需要放在明确事务内:ForUpdate()、ForUpdate(nowait: true, skipLocked: true) 分别对应 FOR UPDATE、FOR UPDATE NOWAIT 和 FOR UPDATE SKIP LOCKED,Provider 不应把不支持的形状悄悄降级为普通查询。
using var uow = fsql.CreateUnitOfWork();
var pending = fsql.Select<Device>()
.ForUpdate(nowait: true, skipLocked: true)
.Where(a => a.Name == "pump-01")
.ToList();
uow.Commit();
实际项目应再核对事务边界、竞争连接、取消/超时和回滚;源码合并不替代这些运行时证据。
关系表和 measurement 不能混写
时序 measurement 使用 TAG 表示维度、FIELD 保存观测值,内置 time 按 Unix 毫秒保存:
[Table(Name = "cpu")]
public sealed class CpuMetric
{
[Column(Name = "time")]
public DateTime Time { get; set; }
[SonnetDBTag]
public string Host { get; set; } = string.Empty;
[SonnetDBField]
public double Usage { get; set; }
}
这条路径和关系表的事务、JOIN、CodeFirst 结构迁移不是同一份合同。关系表的 VECTOR/GEOPOINT 列仍由产品边界拒绝,FOR SHARE 也没有成为本次 Provider 接入的已完成入口。把两个模型分开写清楚,才能让 FreeSql 的调用方知道哪些能力是可复用的,哪些必须回到 SonnetDB 的独立模型合同。

图2:关系表的列、JOIN 和迁移与 measurement 的时间点、TAG 和 FIELD 分开处理。AI 主题示意图,并非全量能力矩阵。
当前发布边界
当前上游合并证明的是源码进入 FreeSql 上游。正式 SonnetDB 4.5 包身份、对应 FreeSql 正式 Provider 包、远程 REST/Frame 组合、远程 DDL 事务、StoredProcedure、schema/table 结构化元数据和生产使用仍需分别验收。不要把 master、本地测试或 README 能力列表写成稳定包承诺。
本文原文保存在 IoTPaper:https://iotpaper.net/articles/freesql/sonnetdb-provider-quickstart/。后续渠道稿件使用这个完整地址作为原文链接;源码和版本事实仍以 IoTSharp/FreeSql 及对应提交为准。