FreeSql + SonnetDB:CodeFirst / DbFirst 实战

从 SonnetDB Provider 的连接、实体标记、CodeFirst、CRUD、事务和锁定读开始,说明 FreeSql 关系表与时序 measurement 的使用边界。

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 和类型边界。

FreeSql SonnetDB 从 C# 实体到表结构、CRUD 和锁定读的工作流示意

图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 的独立模型合同。

FreeSql SonnetDB 关系表与时序 measurement 分离使用的示意图

图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 及对应提交为准。

原文地址:https://iotpaper.net/articles/freesql/sonnetdb-provider-quickstart/

本文对应的源码

  • IoTSharp/FreeSql · c66610d7d8be54e6fb3d9a2a0d33a2b2e6018982

    Provider README、连接入口、关系表/measurement 模型说明和当前能力边界。