PalORM.MySql 5.2.0

<div align="center">

PalORM

面向 Native AOT 的 .NET 11 微 ORM

</div>

• .NET 生态唯一完整支持全链路 Native AOT 的 ORM
• 编译时生成一切——Roslyn 在编译期产出 SQL 构造、参数绑定、对象映射、表结构迁移，运行时零反射、零 IL Emit。Native AOT 全链路验证，原生二进制部署
• 支持 PostgreSQL / MySQL / SQLite。内置多租户隔离、乐观锁、软删除、AES-256 透明加密（SQLite）、审计拦截器、咨询锁、编译时诊断——企业级特性开箱即用，无需样板代码

目录

• 环境要求
• 安装
• 快速开始
• 配置系统
• 特性总览
• 性能基准报告
• 使用示例
• Native AOT
• Scaffold 工具

环境要求

硬件要求

软件要求

数据库兼容性

为什么选择这些版本

• Npgsql 10.0.3：原生支持 PG date/time → DateOnly/TimeOnly、NpgsqlSlimDataSourceBuilder（AOT 友好）、Binary COPY 批量写入
• MySqlConnector 2.6.1：含安全修复 GHSA-473q（zero-config TLS MitM）、MySqlBulkCopy（LOAD DATA LOCAL INFILE）、VECTOR 类型准备
• SQLite3MC 2.3.6：内嵌 SQLite 3.47.2 + AES-256 加密，PCLRaw 跨平台原生二进制加载

安装

<PackageReference Include="PalORM.PostgreSql" Version="5.1.0" />

<PackageReference Include="PalORM.MySql" Version="5.1.0" />

<PackageReference Include="PalORM.Sqlite" Version="5.1.0" />

每个 Provider 包含 PalORM.Core（运行时）和 PalORM.SourceGen（编译时源生成器）。

快速开始

定义实体

using PalORM;

[Table("users")]
public partial class User
{
    [Key] public long Id { get; set; }
    [Column("email")] public string Email { get; set; } = "";
    [Column("created_at")] public DateTime CreatedAt { get; set; }
    [Column("metadata")]
    [OwnedJson(typeof(UserJsonContext))]
    public UserMetadata? Metadata { get; set; }
}

创建会话

using var db = await DataSession<PostgreSqlProvider>.CreateAsync(new DbOptions
{
    ConnectionString = "Host=localhost;Username=user;Password=pass;Database=mydb"
});

CRUD

// 插入
var user = await db.InsertAsync(new User { Email = "alice@example.com", CreatedAt = DateTime.UtcNow });

// 查询
var alice = await db.GetAsync<User>(user.Id);
var all = await db.From<User>().Where($"email LIKE {"%@example.com%"}").ToListAsync();

// 更新
alice.Email = "new@example.com";
await db.UpdateAsync(alice);

// 删除
await db.DeleteAsync<User>(alice.Id);

批量操作

// 批量插入（PG: Binary COPY / MySQL: BulkCopy / SQLite: 多值 INSERT）
await db.BulkInsertAsync(users);

// 批量更新（逐条 + 乐观锁）
await db.BulkUpdateAsync(users);

// 批量更新（v5.0 单语句批量，PG: FROM VALUES / MySQL: CASE WHEN / SQLite: 自动回退逐条）
await db.BulkUpdateBatchAsync(users);

// 批量删除（IN 子句单语句）
await db.BulkDeleteAsync<User>(keyList);

// 批量 UPSERT
await db.BulkMergeAsync(users);

配置系统

预设配置

// 开发环境
var dev = DbOptions.Development(connectionString);

// 生产环境（含连接池配置）
var prod = DbOptions.Production(connectionString, readConnectionString);

// 测试环境（零重试 + 短超时）
var test = DbOptions.Testing(connectionString);

// 环境变量加载（Docker/K8s 友好）
var env = DbOptions.FromEnvironment("PALORM_CONNECTION");

全部配置项

v5.0 连接串自动调优

PalORM v5.0 在 CreateConnection 时自动调优（仅当用户未显式设置时覆盖默认值）：

PostgreSQL（6 项）：

MySQL（5 项）：

SQLite PRAGMA（5 项）：

与主流 ORM 特性对比

版本基准：PalORM 5.0.0（.NET 11）/ Dapper 2.1.79（2025）/ EF Core 10.0.10（2025-11 LTS）/ RepoDb 1.15.1（2025）。单元格依据见下方"对比依据"小节。

PalORM 的核心差异：编译时生成 + 全链路 AOT 兼容 + 三方言批量策略。Dapper 快但运行时反射；EF Core 功能完整但运行时重、AOT 仍实验性；RepoDb 与 PalORM 同为微 ORM 但无源生成，且批量仅 SQL Server。

对比依据

• Dapper 2.1.79：Dapper.AOT（独立包，aot.dapperlib.dev）通过 Roslyn interceptors 生成 AOT 拦截器，但 interceptors 是 C# 实验性特性，非默认启用。
• EF Core 10.0.10：EF Core 10 为 LTS（learn.microsoft.com）。ExecuteUpdateAsync/ExecuteDeleteAsync 仅支持"按 WHERE 单值更新"，无法在单 SQL 内对每行设置不同值。AOT 仍为实验性（issue #35945，CS9137 错误未解决）。Scaffold：dotnet ef dbContext scaffold 完整支持。
• RepoDb 1.15.1：BulkOperation 仅 SQL Server（repodb.net/operation/bulkinsert："It is only supporting the SQL Server RDBMS."），其他方言走 InsertAll（packed statements，非真正二进制 bulk）。ExecuteQueryMultiple 提供多结果集。

特性总览

编译时源生成

Roslyn IIncrementalGenerator 为每个 [Table] 实体生成 RowFactory（物化委托）、CommandFactory（参数绑定）、Migration（三方言 DDL）。FormattableString 参数化杜绝 SQL 注入，WithComparer 优化增量缓存命中率。Native AOT 全链路零 IL。

注解

查询

From<T>() 返回 struct QueryBuilder<T>，链式 .Where() / .OrderBy() / .Take() / .Skip() / .Select() / .GroupBy() / .Having() / .Include() / .ThenInclude()。支持 InnerJoin / LeftJoin / RightJoin、WhereIn / WhereNotIn（自动分批）、CTE、窗口函数、悲观锁（ForUpdate / ForShare）、SQL 预览（AsDryRun）、查询缓存、Keyset 分页。

写入与批量

InsertAsync / UpdateAsync / DeleteAsync / SaveAsync（UPSERT）。批量：

事务与弹性

函数式事务 WithTransaction(callback) 自动 commit/rollback，支持保存点。WithRetry 指数退避重试，WithCircuitBreaker 熔断快速失败。

横切关注点

PostgreSQL 专有

编译时诊断（PALORM001-040）

33 条 Roslyn 分析器规则，按价值分层：

• P0 防运行时崩溃（PALORM001-027 + 031-033）：缺 [Key]、N+1 检测、软删/租户列校验、OwnedJson 上下文验证、无插入/更新列、[Timestamp] 非时间类型、[NotMapped] 冲突、BulkUpdateBatchAsync 对并发实体调用等——把运行时 throw 提前到编译期
• P1 防静默错误（PALORM034-037 + 040）：[Key] 非默认初值让 SaveAsync 永远走 Update、[ConcurrencyCheck]+[IgnoreOnInsert] 让乐观锁基线为 0、#nullable disable 下 NULL 读取崩溃、[Required]+可空矛盾、[TenantAware] 租户列可空绕过隔离——防止不 throw 但数据错/丢失/安全绕过

性能基准报告

测试环境：AMD Ryzen 9 8945HX (32 logical) · Windows 10 22H2 · .NET 11.0.0-preview.6 · BenchmarkDotNet fork (net11) · SQLite 共享内存 10K 行 · PG 18.4 / MySQL 8.4.10 远程

SQLite CRUD（4 ORM 对照）

全表查询 10,000 行

单行插入

主键查询

批量操作（10,000 行）

PalORM BulkInsert 耗时高于 Dapper（源生成 binder + SessionOperationState 门禁开销），但内存分配仅 Dapper 的 40%——GC 压力显著更低。

GC 装箱分析（v5.0 新增）

BulkInsert 装箱 ~24.5%（每行 4 值类型列 × ~32B/装箱）。PG COPY / MySQL BulkCopy 路径不走 DbParameter.Value，已无装箱。

PostgreSQL（远程 PG 18.4）

MySQL（远程 MySQL 8.4.10）

MySQL 单行操作比原生 ADO.NET 快 14~58%——v5.0 连接串调优（AutoEnlist=false / ConnectionReset=false）的收益在远程场景放大。

SQL 构建（纳秒级）

跨方言 BulkUpdateBatch 对照（1K 行）

Native AOT 发布体积

使用示例

事务

await db.WithTransaction(async ct =>
{
    await db.InsertAsync(order, ct);
    await db.BulkInsertAsync(order.Items, ct);
    await db.ExecuteAsync($"UPDATE inventory SET stock = stock - {order.Items.Count} WHERE product_id = {productId}", ct);
});

多结果集（GridReader）

using var grid = await db.QueryMultipleAsync($"SELECT * FROM users WHERE id = {userId}; SELECT * FROM orders WHERE user_id = {userId}");
var user = await grid.ReadFirstAsync<User>();
var orders = await grid.ReadAsync<Order>().ToListAsync();

Keyset 游标分页

var page = await db.From<Order>()
    .Where($"created_at < {cursor}")
    .OrderBy(o => o.CreatedAt, descending: true)
    .Take(20)
    .ToPageAsync();

AuditInterceptor（v5.0）

var db = await DataSession<PostgreSqlProvider>.CreateAsync(new DbOptions
{
    ConnectionString = connectionString,
    Interceptors = [new AuditInterceptor(loggerFactory.CreateLogger("Audit"))]
});

SessionSetupSql（v5.0）

var db = await DataSession<PostgreSqlProvider>.CreateAsync(new DbOptions
{
    ConnectionString = connectionString,
    SessionSetupSql = "SET TIME ZONE 'UTC'; SET search_path TO 'app, public'"
});

AdvisoryXactLock（v5.0 PG 专有）

await db.WithTransaction(async ct =>
{
    await db.AcquireXactLockAsync(resourceKey, ct);  // 阻塞获取
    // 临界区操作...
});
// 事务结束自动释放锁

原生 SQL

var count = await db.ScalarAsync<long>($"SELECT COUNT(*) FROM users WHERE email LIKE {"%@example.com%"}");

编译时 SQL 文件

[SqlFile("Reports/MonthlySales.sql")]
public static partial MonthlySalesReport[] GetMonthlySales();

Native AOT

PalORM 是全链路 Native AOT 兼容的微 ORM：

dotnet publish -c Release -r win-x64 /p:PublishAot=true

AOT 安全保证：

已验证发布：SQLite / PostgreSQL / MySQL 三方言 Native AOT 发布全部成功（win-x64），运行输出 PalORM AOT verification PASSED。

Scaffold 工具

dotnet run --project tools/PalORM.Scaffold -- <connection-string> --dialect sqlite|pg|mysql [--namespace NS] [--output DIR]

三 Provider schema → C# 实体反向工程。40+ 类型映射（含 uuid → Guid、jsonb → string、bytea → byte[]、date → DateOnly、time → TimeOnly）。

架构设计

PalORM.Core           运行时核心（DataSession / QueryBuilder / Resilience / IQueryInterceptor）
PalORM.PostgreSql     Npgsql 适配 + JSONB / NOTIFY / Binary COPY / AdvisoryXactLock
PalORM.MySql          MySqlConnector 适配 + MySqlBulkCopy
PalORM.Sqlite         MDS + SQLite3MC 适配 + PRAGMA 调优
PalORM.SourceGen      Roslyn IIncrementalGenerator（netstandard2.0 编译器插件）
PalORM.Testing        测试辅助（TestEnvironment / TestDb）

零运行时依赖：PalORM.Core 不引用任何第三方 NuGet 包（仅 BCL + ADO.NET 抽象 + 共享框架日志抽象）。

许可证

AGPL-3.0-only