Core.ORM.Sqlite 2.0.72

Core.ORM - 高性能 .NET ORM 框架

forked from ThingsGateway/TORM

开始

从Nuget安装最新版本。

Install-Package Core.ORM

数据库驱动请按需引用对应的子包：Core.ORM.Sqlite、Core.ORM.MySql、Core.ORM.SqlServer、Core.ORM.PostgreSql、Core.ORM.QuestDb。

TORM - 高性能 .NET ORM 框架

轻量级、高性能、功能丰富的对象关系映射框架

ThingsGateway 生态系统中的 ORM 组件，专为高性能场景设计。

</div>

中文

📖 项目简介

TORM 是一个为 .NET 平台设计的轻量级、高性能数据访问组件。TORM 核心和四个关系型 provider 提供完整 ORM 能力；QuestDB、TDengine 与 Apache IoTDB 扩展包使用各数据库的原生协议，提供 schema、批量写入和查询能力，不伪装成关系型 ORM，也不暴露虚假的事务、Queryable 或 Upsert 语义。

✨ 核心特性

🚀 高性能设计

• AOT：支持AOT编译
• 表达式树解析：高效的 LINQ 表达式到 SQL 转换
• 批量操作优化：支持 BulkCopy 高性能批量插入/更新

🗄️ 多数据库支持

关系型 ORM 与时序原生客户端是明确分层的两组能力。QuestDB、TDengine 和 IoTDB 不注册 IDbProvider，也不支持 OrmClient.Queryable<T>()；需要完整 ORM 语义时应使用前四种关系型 provider。

💡 丰富的功能

基础 CRUD 操作

高级功能

• 🔹 Code First：自动创建/更新数据库表结构
• 🔹 分表分库：支持时间分表、数量分表策略
• 🔹 批量操作：BulkCopy 高性能批量导入
• 🔹 事务管理：支持同步/异步事务
• 🔹 AOP 拦截：SQL 执行前后拦截，日志记录
• 🔹 JSON 支持：原生 JSON 类型支持
• 🔹 全局分表语义：实体更新/删除按分表列路由，Distinct、Count、排序和分页在跨表结果上统一执行
• 🔹 一致写入列策略：Insertable、Savable 和各关系型 BulkCopy 统一处理 identity 与 IsOnlyIgnoreInsert
• 🔹 安全 SQL 方言：标识符转义、LIKE 字面量转义和比较方式由 provider 方言配置，不在表达式访问器中硬编码数据库类型
• 🔹 并发保存：数据库原生 Upsert 保持原子语义，fallback 的存在性查询和写入复用同一连接与事务

⏱️ 时序数据库原生客户端

QuestDB

TORM.QuestDb 保留 QuestDB REST /exec 查询和 /imp 导入协议。每个导入批次使用一个临时 CSV 文件并在成功、拒绝、取消或异常后删除；只有服务端明确接受后才返回 Committed，部分拒绝和全部拒绝都会抛出包含数量与原始响应的异常。

using QuestDbDriver;
using TORM.QuestDb;

using var client = new QuestDbClient(new ConnectionStringBuilder("host=127.0.0.1;port=9000"));
var tables = new QuestDbTableClient(client);
await tables.EnsureTableAsync<SensorRow>();

var writer = new QuestDbCsvBulkWriter<SensorRow>(client) { BatchSize = 1000 };
var result = await writer.WriteAsync(rows);
if (result.CommitState != QuestDbCommitState.Committed)
    throw new InvalidOperationException("QuestDB batch was not committed.");

Apache IoTDB

连接串必须显式指定 Model=tree 或 Model=table。Tree 模型需要 RootPath，Table 模型需要 Database；同一个客户端不会在两种模型之间自动探测或失败回退。

using TORM.IoTDB;

var options = IoTdbConnectionOptions.Parse(
    "DataSource=127.0.0.1;Port=6667;Username=root;Password=root;" +
    "Model=tree;RootPath=root.gateway;PoolSize=2;FetchSize=128;ZoneId=UTC");

await using var client = new IoTdbClient(options);
await client.TreeCodeFirst.InitDeviceSchemaAsync<SensorPoint>("device_1001");
var writer = client.CreateTreeWriter<SensorPoint>("device_1001");
writer.BatchSize = 500;
await writer.InsertAsync(points);

Table 模型使用 IoTdbTableSchema、TableCodeFirst 和 CreateTableWriter<T>()；Tree 模型使用 device path、measurement、TreeCodeFirst 和 CreateTreeWriter<T>()。两种模型的查询都返回 IoTdbQueryResult，时间以 UTC 毫秒进入原生协议。

TDengine

TDengine 连接必须显式选择 Protocol=Native 或 Protocol=WebSocket。当前客户端直接管理 transport 和结果生命周期，不再提供 DbConnection、DbCommand、DbDataReader 或 TaosDataOrmClient 兼容外壳。

using TORM.TaosData;

var options = TdengineConnectionOptions.Parse(
    "Host=127.0.0.1;Port=6041;Username=root;Password=taosdata;Protocol=WebSocket");
using var client = new TdengineClient(options);
if (!client.CheckHealth()) throw new InvalidOperationException("TDengine is unavailable.");

var schema = new TdengineSchemaClient(client);
schema.EnsureDatabase("telemetry");
using var reader = client.Query("SELECT server_version() AS version");

Native/WebSocket 的真实异步和取消能力由 client.Capabilities 明确报告；客户端不会用 Task.Run 伪造异步，也不会在协议失败时自动切换 transport。

📊 性能测试

TORM 与国内主流 ORM 框架 的Sqlite性能对比测试结果：

BenchmarkDotNet v0.15.8, Windows 11 (10.0.26200.8037/25H2/2025Update/HudsonValley2)
Intel Core Ultra 9 285H 2.90GHz, 1 CPU, 16 logical and 16 physical cores
.NET SDK 10.0.103
  [Host]    : .NET 10.0.3 (10.0.3, 10.0.326.7603), X64 RyuJIT x86-64-v3
  .NET 10.0 : .NET 10.0.3 (10.0.3, 10.0.326.7603), X64 RyuJIT x86-64-v3

Job=.NET 10.0  Runtime=.NET 10.0  

可以看出，TORM无论是速度还是内存占用都表现优异，得益于TORM是一个没有任何历史包袱的项目，其高性能设计和批量操作优化，在大数据量场景下表现尤为突出。

注：实际性能因数据库类型、数据量、硬件配置等因素会有所不同。建议在实际项目环境中进行测试。

项目结构

TORM/
|-- analyzer/TORM.Generators/     源生成器
|-- src/TORM/                     ORM 核心
|-- src/TORM.Sqlite/              SQLite 驱动
|-- src/TORM.MySql/               MySQL/MariaDB 驱动
|-- src/TORM.SqlServer/           SQL Server 驱动
|-- src/TORM.PostgreSql/          PostgreSQL 驱动
|-- src/TORM.QuestDb/             QuestDB REST SQL、schema 与 CSV writer
|-- src/TORM.IoTDB/               Apache IoTDB Native API Tree/Table 双模型扩展
|-- src/TORM.TaosData/            TDengine Native/WebSocket 原生客户端
|-- samples/TORM.AotDemo/         AOT 示例
|-- benchmark/TORM.Benchmark/     BenchmarkDotNet 基准项目
`-- test/TORM.Test/               自动化测试

构建与测试

dotnet restore TORM.slnx
dotnet build TORM.slnx -c Release
dotnet test test/TORM.Test/TORM.Test.csproj -c Release

真实数据库集成测试使用 SQLite 加六个 Docker 服务：MySQL、PostgreSQL、SQL Server、QuestDB、TDengine 和 Apache IoTDB 2.0.8。固定镜像、端口、账号和连接串保存在 test/TORM.Test/docker-compose.yml 与 test/TORM.Test/docker-test.env。

docker compose -f test/TORM.Test/docker-compose.yml up -d
docker compose -f test/TORM.Test/docker-compose.yml ps
dotnet test test/TORM.Test/TORM.Test.csproj --configuration Release

完整连接变量和 Windows Docker Desktop 注意事项见 数据库集成测试说明，当前生产变更与测试名称的逐项映射见 测试覆盖矩阵。

2026-08-30 的完整 Release 实测结果为 3808/3808 通过、0 失败、0 跳过；测试覆盖四种关系型 provider 的真实 CRUD/事务/分表/索引/BulkCopy，以及 QuestDB、TDengine、IoTDB 的真实原生协议闭环。

运行基准测试：

dotnet run -c Release --project benchmark/TORM.Benchmark/TORM.Benchmark.csproj

基础配置

using TORM;

// 创建 ORM 客户端
using var ormClient = new OrmClient(new OrmConnectionConfig
{
    DatabaseType = OrmDbType.MySql,
    ConnectionString = "Server=localhost;Database=test;Uid=root;Pwd=password;"
});

定义实体

[OrmTable(TableName = "users")]
public class User
{
    [OrmColumn(IsPrimaryKey = true, IsIdentity = true)]
    public long Id { get; set; }
    
    [OrmColumn(ColumnName = "user_name", Length = 50)]
    public string Name { get; set; }
    
    public int Age { get; set; }
    
    public DateTime CreateTime { get; set; }
}

Code First 自动建表

// 自动创建表结构
await ormClient.CodeFirst.InitTableAsync<User>();

📚 功能详解

查询操作

// 基础查询
var list = await ormClient.Queryable<User>().ToListAsync();

// 条件查询
var adults = await ormClient.Queryable<User>()
    .Where(u => u.Age >= 18)
    .ToListAsync();

// 分页查询（返回 PagedList<T>，包含总数）
var page = await ormClient.Queryable<User>()
    .Where(u => u.IsActive)
    .OrderByDescending(u => u.CreateTime)
    .ToPageListAsync(pageNumber: 1, pageSize: 20);

// 聚合查询
var count = await ormClient.Queryable<User>().CountAsync();
var exists = await ormClient.Queryable<User>().AnyAsync();

// 投影查询
var names = await ormClient.Queryable<User>()
    .Select(u => new { u.Id, u.Name })
    .ToListAsync();

// 流式查询（大数据量场景）
await foreach (var user in ormClient.Queryable<User>().ToAsyncEnumerable())
{
    // 逐行处理
}

批量操作

// 批量插入（高性能）
await ormClient.InsertableRange(users).ExecuteAsync();

// BulkCopy 批量导入（最高性能）
await ormClient.BulkCopy<User>().BulkInsertAsync(users);

// 批量更新
await ormClient.BulkCopy<User>().BulkUpdateAsync(users);

// 批量保存（自动判断插入/更新）
await ormClient.BulkCopy<User>().BulkMergeAsync(users);

分表操作

定义分表实体：

// 按月分表：表名后缀格式 _yyyyMM
[OrmTable(TableName = "logs", SplitType = SplitTableType.Month, SplitColumn = nameof(CreateTime))]
public class Log
{
    [OrmColumn(IsPrimaryKey = true, IsIdentity = true)]
    public long Id { get; set; }
    
    public string Message { get; set; }
    
    // 分表依据列（必须为 DateTime 类型）
    public DateTime CreateTime { get; set; }
}

// 按记录数分表：每 10000 条自动创建新表
[OrmTable(TableName = "sensor_data", MaxRowCount = 10000)]
public class SensorData
{
    [OrmColumn(IsPrimaryKey = true, IsIdentity = true)]
    public long Id { get; set; }
    
    public double Value { get; set; }
}

// 混合策略：按月分表 + 每月内按记录数分表
[OrmTable(TableName = "events", 
    SplitType = SplitTableType.Month, 
    SplitColumn = nameof(EventTime),
    MaxRowCount = 50000)]
public class Event
{
    [OrmColumn(IsPrimaryKey = true, IsIdentity = true)]
    public long Id { get; set; }
    
    public DateTime EventTime { get; set; }
}

分表操作示例：

// 分表查询（自动跨所有分表查询，可指定时间范围）
var list = await ormClient.SplitQueryableAsync<Log>(
    query => query.Where(l => l.Message.Contains("error")),
    startTime: DateTime.Now.AddDays(-30),
    endTime: DateTime.Now
);

// 分表插入（自动路由到正确的分表）
await ormClient.SplitInsertableAsync(logs);

// 分表更新
await ormClient.SplitUpdatableAsync(logs, update => update.Set(l => l.Message, "updated"));

// 分表删除
await ormClient.SplitDeletableAsync(logs);

分表类型说明：

事务管理

await ormClient.UseTranAsync(async () =>
{
    await ormClient.InsertableRange(addModels).ExecuteAsync().ConfigureAwait(false);
}).ConfigureAwait(false);

AOP 日志拦截

// SQL执行前日志
ormClient.Aop.OnLogExecuting = (sql, parameters) =>
{
    Console.WriteLine($"执行SQL: {sql}");
};

// SQL执行后日志
ormClient.Aop.OnLogExecuted = (sql, parameters, elapsed) =>
{
    Console.WriteLine($"SQL执行耗时: {elapsed.TotalMilliseconds}ms");
};

// 插入/更新前修改值
ormClient.Aop.OnDataExecuting = (args) =>
{
    if (args.DataExecutingType == DataExecutingType.Insert)
    {
        // 自动填充创建时间
        if (args.Entity is BaseEntity entity)
        {
            entity.CreateTime = DateTime.Now;
        }
    }
};

Release 构建会生成 NuGet 包并输出到上级 nupkgs 目录。

相关资源

• Docker 集成测试：test/TORM.Test/README.docker-tests.md
• 当前变更测试矩阵：test/TORM.Test/TEST_COVERAGE_MATRIX.md
• 官方文档：https://runtime.thingsgateway.cn/
• Gitee：https://gitee.com/ThingsGateway/TORM
• GitHub：https://github.com/kimdiego2098/ThingsGateway
• QQ 群：605534569

许可证

本项目使用 Apache-2.0 协议。