PalORM.Core 6.8.0

.NET 11.0 This package targets .NET 11.0. The package is compatible with this framework or higher. 
dotnet add package PalORM.Core --version 6.8.0
                    


                    

                
NuGet\Install-Package PalORM.Core -Version 6.8.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="PalORM.Core" Version="6.8.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="PalORM.Core" Version="6.8.0" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="PalORM.Core" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add PalORM.Core --version 6.8.0
                    


                    

                
#r "nuget: PalORM.Core, 6.8.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package PalORM.Core@6.8.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=PalORM.Core&version=6.8.0
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=PalORM.Core&version=6.8.0
                    


                            Install as a Cake Tool

<div align="center">

PalORM

面向 Native AOT 的 .NET 11 微 ORM：编译时生成一切，运行时零反射

.NET NuGet CI License

Native AOT Diagnostics Dialects

简体中文 | English

AOT 原生、编译期可验证、SQL 可控的微 ORM

</div>

Roslyn 源生成器在编译期产出 SQL 构造、参数绑定、对象映射与迁移 DDL，运行时零反射、零 IL Emit；支持 PostgreSQL / MySQL / SQLite 三方言，多租户、乐观锁、软删除、审计、咨询锁等企业级特性开箱即用。

目录

本文档 深度文档（docs/）
✨ 特性 🚀 快速开始 功能特性全景（源码级） AOT 部署指南
🆚 与主流 ORM 对比 📖 使用 API 参考 性能基准规范
📊 性能 ✅ 最佳实践速查 架构设计 发布规范
📦 安装 🔧 配置 架构决策（ADR） 编码规范
🔄 升级指南 🧰 开发 贡献指南 变更日志
💬 社区 📄 许可证

✨ 特性

  • 编译期生成：Roslyn 源生成器为每个 [Table] 实体生成 RowFactory、CommandFactory 与三方言 Migration DDL，为 [Projection] DTO 生成物化委托，运行时零反射、零 IL Emit。
  • 编译期安全网：45 条 Roslyn 诊断把缺主键、租户列可空绕过隔离、乐观锁基线为 0、循环内 N+1 等问题拦在构建期，错误可跳转声明位置。
  • 全链路 Native AOT：SQLite / PostgreSQL / MySQL 三方言 AOT 发布与原生运行全部通过，消费方不需要 TrimmerRootAssembly。
  • 地板级性能：单行 CRUD 与 ADO.NET 手写地板同量级，批量写按方言自动选择 PG Binary COPY、MySQL LOAD DATA、SQLite 行预编译与 json_each 批删，Web 一请求一会话形态内置会话池。
  • 企业级横切：多租户列隔离、乐观锁、软删除、审计拦截器、读写分离、咨询锁、弹性重试与熔断开箱即用。
  • SQL 资产编译期管理：[SqlFile] 嵌入并校验 .sql，[SqlTemplate] 把插值 SQL 常量化，AutoTagging 自动注入“文件:行号 成员”定位注释。
  • 运维与可观测：健康检查、跨方言统一异常族、OpenTelemetry tracing 与 metrics 内置。
  • 方言专属能力：PG 的 UNNEST、咨询锁、LISTEN/NOTIFY、pgvector 与 JSONB 路径查询，MySQL 的 local_infile 降级与 UPDATE JOIN，SQLite 的 AES-256 加密与 PRAGMA 自动调优。
  • Schema 与种子：MigrateAsync 按外键拓扑序执行三方言 DDL，SeedAsync 事务内幂等种子，ValidateSchemaAsync 对照实体返回缺失列。
  • 零依赖核心：PalORM.Core 不引用第三方 NuGet 包，仅 BCL 与 ADO.NET 抽象。

🆚 与主流 ORM 对比

版本基准（2026-10-26 核对 NuGet 最新）：PalORM 6.7.0 / Dapper 2.1.89 / RepoDb 1.17.0（仓库基准套件实际引用版本）；EF Core 10.0.13（10.x LTS 最新补丁，对比所引）。

特性 PalORM Dapper EF Core RepoDb
Native AOT 全链路 ✓ 源生成验证 △ Dapper.Aot 可选（实验性拦截器） ❌ 实验性，生产不推荐 △ 全包 NativeAOT/trimming 兼容标注 + SQLite AOT 冒烟测试（反射路线，无源生成）
编译时类型诊断 ✓ 45 条（42 分析器 + 3 生成器），错误可跳转声明位置 ❌ 运行时失败 △ 迁移检查（设计时） ❌ 运行时失败
编译时 SQL 预构建 ✓ Roslyn 源生成 ❌ 运行时拼接 △ 预编译查询（实验性） ❌ 运行时表达式树
运行时反射 零 △ 首次反射 + IL Emit 缓存 △ 表达式树编译 △ 反射 + 表达式编译（IL Emit 已移除）
查询书写范式 ✓ 链式构建器（SQL 显式可见）+ FormattableString 原生 SQL △ 手写 SQL ✓ LINQ 强类型翻译 △ QueryBuilder
模型构建成本 ✓ 编译期生成，零运行时构建 ✓ 无模型（首次反射 + 缓存） △ 运行时构建（Compiled Model 需手动再生成） ✓ 首次操作缓存
三方言批量策略 ✓ COPY / BulkCopy / 行预编译·多值 / = ANY 数组 ❌ 手写多值 SQL △ Provider 各异 △ Bulk 族扩展包覆盖 13+ 数据库（SQL Server/MySQL/Oracle 等，部分 preview）
单语句多行 UPDATE ✓ FROM VALUES / UPDATE JOIN VALUES ROW / CASE WHEN ❌ ❌ ExecuteUpdate 仅按 WHERE 单值 ❌
IN 集合参数翻译 ✓ 500 键自动分批 + PG = ANY 数组形态 ❌ 手写 ✓ EF10 起多参数为默认，翻译模式可配（JSON/常量） △ DeleteAll 内部按 MaxParameterCount 分批；查询侧 IN 手写
批量 UPSERT ✓ BulkMergeAsync（ON CONFLICT / ON DUPLICATE KEY，冲突更新限定本租户） ❌ 手写 ❌ 需 raw SQL △ Merge 经扩展包覆盖多 Provider（SQL Server/MySQL/Oracle 等）
乐观锁 ✓ [ConcurrencyCheck] 自动；批量单语句（PG/MySQL，能力不全回退 DbBatch） ❌ 手写 ✓ RowVersion 自动 ❌ 手写
软删除 ✓ [SoftDelete] 自动过滤（含批量删转 UPDATE） ❌ ✓ 全局查询过滤器（EF10 命名过滤器可按名禁用） ❌
多租户列隔离 ✓ [TenantAware] 编译时；批量写跨租户护栏 ❌ △ 需手动实现 ❌
值转换 + 枚举存储 ✓ [Converter] / 枚举三策略（int32/int64/文本）编译时发射 △ TypeHandler 手写 ✓ ValueConverter / HasConversion（运行时） △ TypeHandler
读副本路由 ✓ ParallelReadScope + 查询族 readFromReplica ❌ △ 需手动配置多上下文 ❌
Schema 自动迁移 ✓ MigrateAsync + 并发竞态容错（重复对象即跳过） ❌（无迁移系统） ✓ Migrations（最全面） ❌
OwnedJson 编译时安全 ✓ [OwnedJson] + 源生成 △ PropertyHandler 映射（运行时反射标注 RUC/DC；AOT 需传源生成 JsonTypeInfo） △ Owned Types（运行时） ❌
审计拦截器 ✓ ❌ ✓ Interceptors ❌
咨询锁 ✓ pg_advisory_xact_lock ❌ ❌ ❌
会话级 SET ✓ SessionSetupSql ❌ ❌ ❌
SQL 文件嵌入 ✓ [SqlFile] 编译时校验 ❌ ❌ ❌
断路器 + 重试 ✓ 内置（HalfOpen 探针槽位并发安全） ❌ 需 Polly △ 执行策略 ❌
查询缓存 ✓ WithCache 有界缓存 + TTL + EvictQueryCache 收窄 ❌ ❌ 需第三方拦截器 ✓ 原生 cacheKey 参数
流式消费 ✓ QueryAsyncEnumerable / ForEachAsync △ 手写 CommandBehavior ✓ AsAsyncEnumerable 原生 ❌
可观测性（OTel） ✓ WithMetrics / WithTracing 内置 ❌ △ 第三方 instrumentation 包 △ 自建遥测扩展包（Telemetry.Core/Default，非 OTel）
SQL 预览 ✓ AsDryRun（SQL + 参数） ❌ ✓ ToQueryString △ 构建器层 GetString
悲观锁 ✓ ForUpdate / ForShare 链式 ❌ 手写 SQL △ 本体无内置（PG provider 扩展） ❌
导航装配（对象图） △ Include 生成 JOIN 不装配（micro-ORM 取舍，按父分组自行配对） △ multi-mapping 手写 ✓ Include 完整装配 + 变更追踪 ❌
变更追踪 / 工作单元 ❌ 无状态设计（零追踪开销） ❌ ✓ ChangeTracker（身份解析 + 状态机） ❌
JSON 列查询 △ WhereJson JSONB 路径查询（PG 专有）；映射见上方 [OwnedJson] △ 手写 SQL ✓ EF7+ JSON 列映射 + 路径查询（EF10：SQL Server 2025 json 类型、ExecuteUpdate 支持） △ PropertyHandler 映射，无路径查询
CTE / 窗口函数 ✓ 链式 API △ 原生 SQL 字符串 △ LINQ 翻译（部分） △ 原生 SQL
多结果集 ✓ GridReader ✓ QueryMultiple ❌ ✓ ExecuteQueryMultiple
Keyset 分页 ✓ ToPageAsync ❌ ❌ ❌
Scaffold 工具 ✓ 三 Provider ❌ ✓ dotnet ef dbContext scaffold ❌
连接串自动调优 ✓ PG 6 / MySQL 5 / SQLite 9 项 ❌ ❌ ❌
会话池化 ✓ DataSessionPool 内置（32 并发 P99 −18%） ❌ ✓ DbContextPool ❌
存储过程 ✓ StoredProc 强类型输入/输出参数 ✓ DynamicParameters △ FromSqlRaw 间接 ✓ ExecuteQuery
整事务瞬时错误重试 ✓ WithTransactionRetry（方言错误码重放，at-least-once） ❌ ✓ EnableRetryOnFailure 执行策略 ❌
数据库健康检查 ✓ HealthCheckAsync ❌ 手写 SELECT 1 ✓ CanConnect() ❌
SQL 文件 / 模板资产化 ✓ [SqlFile] 方言条件段 + [SqlTemplate] 常量化，编译期校验 ❌ ❌ ❌
SQL 定位注释 ✓ AutoTagging 自动注入「文件:行号 成员」（opt-in） ❌ △ TagWith() 手动 ❌
pgvector ✓ 文本边界路线（::vector 写入，AOT 兼容） ❌ △ 第三方扩展包 ❌
种子数据 ✓ SeedAsync 事务内幂等 Upsert ❌ ✓ HasData（设计时） ❌
BulkInsert 内存 SQLite ≈ Dapper 的 40%（PG / MySQL 5%~7%） 基线 最高（ChangeTracker） 中等
数据库覆盖广度 三方言（深度调优） 任意 ADO.NET（方言自理） 官方 Provider 矩阵（SQL Server / SQLite / PG / MySQL / Cosmos…） 15+ Provider（1.16/1.17 大幅扩容）
核心包 NuGet 依赖 零 零 高（多包拆分） 中等
目标框架 net11.0（单目标） 多目标（netstandard2.0+） 多目标（net8+） 多目标（netstandard2.0+）
许可证 Apache-2.0 Apache-2.0 MIT Apache-2.0

核心差异：编译时生成 + 全链路 AOT 兼容 + 三方言批量策略（COPY / BulkCopy / 行预编译 / 数组）。Dapper 快但运行时反射；EF Core 功能完整但运行时重、AOT 仍实验性；RepoDb 同为微 ORM 但无源生成，Bulk 族经扩展包扩展到 SQL Server/MySQL/Oracle 等 13+ 数据库。 RepoDb 1.16/1.17 开始已经移除掉了IL Emit实现，现在已经兼容AOT，使用表达式路径实现。(RepoDb早点实现AOT，我就不做这个ORM了，没想到用AI还要搞四个月 ☹)。

📊 性能

测试环境：AMD Ryzen 9 8945HX（32 逻辑核）· Windows 10 22H2 · .NET 11 RC2 · SQLite 临时文件库（WAL + 64 MB cache + mmap）· PG 18.6 / MySQL 8.4.11 本机容器。四臂同进程同轮采集、同数据同量具：ADO.NET（手写性能地板）/ Dapper 2.1.89 / FreeSql 3.5.311 / PalORM——每臂用其生态惯用的最优写法，每操作两遍反序臂序取中位（消除臂序相位）。

数据批次：2026-10-25 夜，代码 3affd97。CrossBench 四臂批 crossbench-20261025-213235.json + PerfCli full 三完整批（416 项/批）；同批门禁 BDN 27/27、结果库 171 项 0 FAIL。数字由冻结模板脚本从批次 JSON 推导（scripts/crossbench-report.cs），完整报告见 bench/reports/。

读表：每格 = 时间 [对 ADO 倍数] / 内存 [对 ADO 倍数]；[1.00] = ±0.5% 持平带；≤0.67 或 ≥1.5 越线加粗；📌 = 越线待判读；🏆 = 该格最快臂。色标（正 % = 比基准慢/费）：🟢 强优 ≤−30% · 🟩 中优 −29%~−10% · 🔹 微优 −9%~−1% · 🔸 微劣 +1%~+9% · 🟧 中劣 +10%~+29% · 🟥 强劣 ≥+30%。

总览（四臂 × 三方言 × 14 操作 = 69 格）

CRUD 单行与读（基准 = ADO [1.00]）

  • 🥇 GetByKey SQLite：PalORM 0.78（快 22%），FreeSql 4.70（慢 370%，全方言最差 5.00）
  • QueryAll MySQL 20000 分配：PalORM 0.91（快 9%），Dapper 1.11（慢 11%）
  • Insert SQLite：PalORM 1.00（持平），FreeSql 1.74（慢 74%）

批量处理（基准 = ADO [1.00]）

  • 🥇 BulkDelete PG 20000：PalORM 0.44（快 56%），分配 0.10（快 90%）
  • 🥇 UpsertBatch PG 20000：PalORM 0.60（快 40%），分配 0.37（快 63%）
  • BulkInsert SQLite 20000：PalORM 1.03（慢 3%），Dapper 1.68（慢 68%），FreeSql 3.99（慢 299%）
  • BulkUpdate 三方言两档：PalORM 0.89~1.03，Dapper 最差 3.77（慢 277%）

事务（基准 = ADO [1.00]）

  • PalORM 全项 0.95~1.15，最快 TxHundredInserts MySQL 0.95
  • FreeSql 最差 TxRollback SQLite 13.26，Dapper 最差 TxRollback SQLite 3.86
  • EnumInserts SQLite 分配：PalORM 1.00（持平），FreeSql 8.42（慢 742%）

最快胜场

臂 最快 / 69 格
ADO.NET（地板） 33（48%）
PalORM 31（45%）
Dapper 5（7%）
FreeSql 0（0%）

P/ADO 中位 1.00（贴平手写 SQL 地板），全距 0.44~1.15。

表一：CRUD 单行与读（三方言，两档）

胜场：ADO 15 · PalORM 11 · Dapper 4 · FreeSql 0

操作 测什么 总评
GetByKey 主键单行点查 PalORM 贴地板（SQLite 会话税被 SQL 常量缓存抵消）；FreeSql 全方言最慢（表达式每次求值）
GetAllAsync 全表直查 API（PalORM 专用 GetAllAsync，其余同 QueryAll） 联网方言四臂接近；SQLite Dapper（反射物化）与 FreeSql（表达式管线）明显偏慢
QueryAll 全表物化查询（From<T>().ToListAsync / Select.ToList） 同 GetAllAsync：PalORM ≈ ADO 地板，SQLite 两竞品明显偏慢
Insert 单行插入（自增主键） 联网方言 fsync 主导四臂持平；SQLite PalORM 持平、FreeSql 明显偏慢（表达式管线）
Update 单行整行更新 联网方言 fsync 主导持平；FreeSql 在 SQLite 与 MySQL 明显偏慢（表达式管线）

SQLite

操作 档 🏆 ADO.NET PalORM Dapper FreeSql
GetByKey 2000 🏆 PalORM 7.4 µs [1.00] / 2.1KB [1.00] 5.8 µs [0.78] / 2.1KB [1.02] 9.7 µs [1.30] / 2.8KB [1.34] 34.8 µs [4.70] / 10.2KB [4.86]
GetAllAsync 2000 🏆 PalORM 957.8 µs [1.00] / 308KB [1.00] 949.0 µs [0.99] / 294KB [0.95] 1.36 ms [1.42] / 513KB [1.66] 1.38 ms [1.44] / 314KB [1.02]
QueryAll 2000 🏆 PalORM 956.6 µs [1.00] / 308KB [1.00] 947.0 µs [0.99] / 292KB [0.95] 1.34 ms [1.40] / 513KB [1.66] 1.37 ms [1.43] / 314KB [1.02]
Insert 2000 ADO 17.0 µs [1.00] / 2.8KB [1.00] 17.0 µs [1.00] / 2.7KB [0.97] 17.8 µs [1.05] / 3.5KB [1.28] 29.6 µs [1.74] / 5.7KB [2.06]
Update 2000 ADO 7.0 µs [1.00] / 2.5KB [1.00] 7.2 µs [1.01] / 2.9KB [1.15] 7.8 µs [1.11] / 3.3KB [1.30] 19.1 µs [2.71] / 7.4KB [2.94]
GetByKey 20000 ADO 6.0 µs [1.00] / 2.1KB [1.00] 6.2 µs [1.04] / 2.2KB [1.02] 7.1 µs [1.18] / 2.8KB [1.33] 30.0 µs [5.00] / 10.4KB [4.93]
GetAllAsync 20000 ADO 9.52 ms [1.00] / 3.3MB [1.00] 9.55 ms [1.00] / 2.9MB [0.89] 13.72 ms [1.44] / 5.3MB [1.61] 13.82 ms [1.45] / 3.3MB [1.01]
QueryAll 20000 🏆 PalORM 9.54 ms [1.00] / 3.3MB [1.00] 9.48 ms [0.99] / 2.9MB [0.89] 13.66 ms [1.43] / 5.3MB [1.61] 13.78 ms [1.44] / 3.3MB [1.01]
Insert 20000 🏆 PalORM 17.1 µs [1.00] / 2.8KB [1.00] 16.9 µs [0.99] / 2.7KB [0.97] 18.0 µs [1.06] / 3.6KB [1.31] 29.1 µs [1.71] / 5.7KB [2.06]
Update 20000 ADO 7.1 µs [1.00] / 2.5KB [1.00] 7.1 µs [1.00] / 2.9KB [1.15] 8.0 µs [1.12] / 3.3KB [1.30] 21.4 µs [3.01] / 7.4KB [2.95]

MySQL

操作 档 🏆 ADO.NET PalORM Dapper FreeSql
GetByKey 2000 ADO 190.0 µs [1.00] / 4.5KB [1.00] 190.8 µs [1.00] / 4.9KB [1.09] 198.4 µs [1.04] / 5.8KB [1.30] 414.6 µs [2.18] / 16.5KB [3.68]
GetAllAsync 2000 ADO 1.09 ms [1.00] / 398KB [1.00] 1.10 ms [1.00] / 384KB [0.96] 1.13 ms [1.04] / 447KB [1.12] 1.36 ms [1.24] / 407KB [1.02]
QueryAll 2000 🏆 PalORM 1.11 ms [1.00] / 398KB [1.00] 1.10 ms [0.99] / 384KB [0.96] 1.13 ms [1.02] / 447KB [1.12] 1.36 ms [1.22] / 407KB [1.02]
Insert 2000 🏆 PalORM 3.84 ms [1.00] / 16.3KB [1.00] 3.66 ms [0.95] / 16.3KB [1.00] 3.79 ms [0.98] / 16.4KB [1.01] 4.09 ms [1.06] / 22.1KB [1.35]
Update 2000 🏆 PalORM 193.4 µs [1.00] / 5.3KB [1.00] 189.7 µs [0.98] / 5.8KB [1.09] 198.6 µs [1.03] / 5.2KB [0.97] 402.8 µs [2.08] / 13.2KB [2.47]
GetByKey 20000 ADO 194.3 µs [1.00] / 4.5KB [1.00] 194.7 µs [1.00] / 4.9KB [1.09] 204.5 µs [1.05] / 5.9KB [1.30] 421.9 µs [2.17] / 16.8KB [3.72]
GetAllAsync 20000 Dapper 9.95 ms [1.00] / 4.0MB [1.00] 9.84 ms [0.99] / 3.7MB [0.91] 9.84 ms [0.99] / 4.5MB [1.11] 10.50 ms [1.06] / 4.1MB [1.00]
QueryAll 20000 ADO 9.47 ms [1.00] / 4.0MB [1.00] 9.76 ms [1.03] / 3.7MB [0.91] 9.82 ms [1.04] / 4.5MB [1.11] 10.57 ms [1.12] / 4.1MB [1.00]
Insert 20000 🏆 PalORM 3.90 ms [1.00] / 16.7KB [1.00] 3.85 ms [0.99] / 16.7KB [0.99] 3.87 ms [0.99] / 16.4KB [0.98] 4.27 ms [1.10] / 22.6KB [1.35]
Update 20000 ADO 167.3 µs [1.00] / 5.1KB [1.00] 176.8 µs [1.06] / 5.7KB [1.11] 174.3 µs [1.04] / 5.1KB [1.00] 400.3 µs [2.39] / 13.3KB [2.59]

PostgreSQL

操作 档 🏆 ADO.NET PalORM Dapper FreeSql
GetByKey 2000 Dapper 197.4 µs [1.00] / 3.0KB [1.00] 198.2 µs [1.00] / 3.4KB [1.13] 192.8 µs [0.98] / 3.2KB [1.09] 263.5 µs [1.33] / 12.0KB [4.04]
GetAllAsync 2000 🏆 PalORM 665.7 µs [1.00] / 240KB [1.00] 662.2 µs [0.99] / 225KB [0.94] 725.4 µs [1.09] / 442KB [1.85] 742.8 µs [1.12] / 244KB [1.02]
QueryAll 2000 ADO 637.3 µs [1.00] / 239KB [1.00] 664.5 µs [1.04] / 225KB [0.94] 668.5 µs [1.05] / 442KB [1.85] 735.0 µs [1.15] / 244KB [1.02]
Insert 2000 ADO 1.36 ms [1.00] / 7.5KB [1.00] 1.40 ms [1.03] / 7.5KB [1.01] 1.41 ms [1.03] / 7.3KB [0.98] 1.42 ms [1.04] / 11.0KB [1.47]
Update 2000 Dapper 1.39 ms [1.00] / 7.3KB [1.00] 1.40 ms [1.01] / 7.8KB [1.06] 1.38 ms [1.00] / 7.2KB [0.97] 1.43 ms [1.03] / 13.0KB [1.77]
GetByKey 20000 ADO 199.5 µs [1.00] / 3.0KB [1.00] 199.6 µs [1.00] / 3.4KB [1.13] 200.6 µs [1.01] / 3.3KB [1.09] 271.3 µs [1.36] / 12.1KB [4.06]
GetAllAsync 20000 ADO 5.14 ms [1.00] / 2.5MB [1.00] 5.15 ms [1.00] / 2.2MB [0.86] 5.34 ms [1.04] / 4.5MB [1.79] 5.81 ms [1.13] / 2.5MB [1.00]
QueryAll 20000 ADO 5.12 ms [1.00] / 2.5MB [1.00] 5.20 ms [1.02] / 2.2MB [0.86] 5.37 ms [1.05] / 4.5MB [1.79] 5.92 ms [1.16] / 2.5MB [1.00]
Insert 20000 🏆 PalORM 1.37 ms [1.00] / 7.5KB [1.00] 1.36 ms [1.00] / 7.5KB [1.00] 1.38 ms [1.01] / 7.1KB [0.96] 1.44 ms [1.05] / 11.0KB [1.47]
Update 20000 Dapper 1.44 ms [1.00] / 7.7KB [1.00] 1.39 ms [0.96] / 7.8KB [1.01] 1.39 ms [0.96] / 7.0KB [0.91] 1.48 ms [1.03] / 13.1KB [1.70]

表二：批量处理（三方言，两档）

胜场：PalORM 14 · ADO 10 · Dapper 0 · FreeSql 0

操作 测什么 总评
BulkInsert 批量插入（SQLite 行预编译 / PG COPY / MySQL BulkCopy） PalORM 与 ADO 同形态贴平；Dapper/FreeSql 批量路径全方言偏慢，PG/MySQL 大档差距最大
BulkUpdate 批量更新（SQLite 逐条裹事务 / PG UPDATE FROM VALUES / MySQL CASE WHEN） PalORM 三方言与 ADO 同形态贴平；Dapper/FreeSql 无集合式封装，明显偏慢
BulkDelete 批量删除（SQLite json_each 单参数 / PG = ANY 数组 / MySQL IN 分批） PG 数组形态快于 ADO 的 IN 占位符；SQLite json_each 与 MySQL 分批接近地板
UpsertBatch 批量 UPSERT（ON CONFLICT / ON DUPLICATE KEY） PG 数组形态快于 ADO 与其余臂；SQLite 四臂同形态贴平；MySQL Dapper/FreeSql 偏慢

SQLite

操作 档 🏆 ADO.NET PalORM Dapper FreeSql
BulkInsert 2000 ADO 2.52 ms [1.00] / 1.7MB [1.00] 2.54 ms [1.01] / 1.7MB [1.00] 4.55 ms [1.81] / 4.3MB [2.48] 10.61 ms [4.21] / 6.5MB [3.79]
BulkUpdate 2000 🏆 PalORM 2.31 ms [1.00] / 1.7MB [1.00] 2.30 ms [1.00] / 1.8MB [1.04] 8.69 ms [3.77] / 6.3MB [3.75] 13.38 ms [5.80] / 7.0MB [4.15]
BulkDelete 2000 🏆 PalORM 803.4 µs [1.00] / 197KB [1.00] 797.3 µs [0.99] / 198KB [1.01] 21.65 ms [26.95] / 1.6MB [8.12] 1.53 ms [1.91] / 568KB [2.88]
UpsertBatch 2000 ADO 2.38 ms [1.00] / 1.7MB [1.00] 2.41 ms [1.01] / 1.7MB [1.01] 4.81 ms [2.02] / 4.2MB [2.50] 3.59 ms [1.51] / 2.5MB [1.47]
BulkInsert 20000 ADO 28.19 ms [1.00] / 17.2MB [1.00] 29.04 ms [1.03] / 17.2MB [1.00] 47.26 ms [1.68] / 42.5MB [2.48] 112.42 ms [3.99] / 66.1MB [3.85]
BulkUpdate 20000 🏆 PalORM 25.82 ms [1.00] / 17.0MB [1.00] 25.52 ms [0.99] / 17.6MB [1.04] 90.97 ms [3.52] / 63.5MB [3.74] 134.45 ms [5.21] / 73.4MB [4.32]
BulkDelete 20000 🏆 PalORM 8.44 ms [1.00] / 2.0MB [1.00] 8.18 ms [0.97] / 2.0MB [1.00] 218.58 ms [25.89] / 15.6MB [7.71] 15.87 ms [1.88] / 5.9MB [2.94]
UpsertBatch 20000 ADO 25.54 ms [1.00] / 17.0MB [1.00] 26.19 ms [1.03] / 17.1MB [1.01] 59.79 ms [2.34] / 42.4MB [2.50] 40.46 ms [1.58] / 25.8MB [1.52]

MySQL

操作 档 🏆 ADO.NET PalORM Dapper FreeSql
BulkInsert 2000 🏆 PalORM 11.60 ms [1.00] / 476KB [1.00] 11.41 ms [0.98] / 480KB [1.01] 24.56 ms [2.12] / 6.7MB [14.30] 17.33 ms [1.49] / 3.2MB [6.95]
BulkUpdate 2000 🏆 PalORM 10.87 ms [1.00] / 4.6MB [1.00] 9.68 ms [0.89] / 3.7MB [0.80] 11.05 ms [1.02] / 6.5MB [1.41] 9.83 ms [0.90] / 2.1MB [0.45]
BulkDelete 2000 ADO 12.07 ms [1.00] / 882KB [1.00] 12.10 ms [1.00] / 808KB [0.92] 12.10 ms [1.00] / 1.3MB [1.56] 17.46 ms [1.45] / 608KB [0.69]
UpsertBatch 2000 🏆 PalORM 8.28 ms [1.00] / 2.9MB [1.00] 8.03 ms [0.97] / 2.5MB [0.85] 10.62 ms [1.28] / 6.6MB [2.28] 9.06 ms [1.09] / 2.5MB [0.86]
BulkInsert 20000 ADO 58.38 ms [1.00] / 4.4MB [1.00] 59.30 ms [1.02] / 4.4MB [1.00] 257.38 ms [4.41] / 66.5MB [14.95] 116.99 ms [2.00] / 33.2MB [7.47]
BulkUpdate 20000 🏆 PalORM 88.98 ms [1.00] / 14.6MB [1.00] 88.76 ms [1.00] / 13.7MB [0.94] 139.83 ms [1.57] / 64.5MB [4.42] 92.33 ms [1.04] / 21.8MB [1.49]
BulkDelete 20000 🏆 PalORM 75.24 ms [1.00] / 8.4MB [1.00] 70.44 ms [0.94] / 3.5MB [0.42] 76.69 ms [1.02] / 13.2MB [1.57] 182.86 ms [2.43] / 6.2MB [0.74]
UpsertBatch 20000 ADO 75.36 ms [1.00] / 12.9MB [1.00] 79.85 ms [1.06] / 12.6MB [0.98] 131.34 ms [1.74] / 66.1MB [5.15] 124.68 ms [1.65] / 25.8MB [2.01]

PostgreSQL

操作 档 🏆 ADO.NET PalORM Dapper FreeSql
BulkInsert 2000 ADO 4.72 ms [1.00] / 341KB [1.00] 4.90 ms [1.04] / 343KB [1.01] 16.82 ms [3.56] / 6.7MB [20.10] 12.95 ms [2.74] / 3.8MB [11.56]
BulkUpdate 2000 ADO 5.28 ms [1.00] / 418KB [1.00] 5.45 ms [1.03] / 422KB [1.01] 19.04 ms [3.61] / 6.5MB [15.99] 14.07 ms [2.67] / 2.7MB [6.64]
📌BulkDelete 2000 🏆 PalORM 3.49 ms [1.00] / 784KB [1.00] 2.27 ms [0.65] / 89.2KB [0.11] 3.97 ms [1.14] / 1.3MB [1.71] 5.88 ms [1.68] / 571KB [0.73]
📌UpsertBatch 2000 🏆 PalORM 14.90 ms [1.00] / 2.7MB [1.00] 7.53 ms [0.51] / 445KB [0.16] 20.29 ms [1.36] / 6.7MB [2.47] 16.17 ms [1.09] / 2.7MB [1.01]
BulkInsert 20000 ADO 19.89 ms [1.00] / 3.3MB [1.00] 20.29 ms [1.02] / 3.3MB [1.00] 197.63 ms [9.94] / 66.9MB [20.55] 110.04 ms [5.53] / 39.6MB [12.15]
BulkUpdate 20000 🏆 PalORM 68.68 ms [1.00] / 4.1MB [1.00] 61.05 ms [0.89] / 4.1MB [0.99] 224.10 ms [3.26] / 65.4MB [16.00] 124.58 ms [1.81] / 28.3MB [6.92]
📌BulkDelete 20000 🏆 PalORM 25.03 ms [1.00] / 7.6MB [1.00] 10.99 ms [0.44] / 815KB [0.10] 27.89 ms [1.11] / 13.0MB [1.71] 59.11 ms [2.36] / 6.0MB [0.78]
📌UpsertBatch 20000 🏆 PalORM 137.91 ms [1.00] / 11.6MB [1.00] 83.33 ms [0.60] / 4.3MB [0.37] 219.95 ms [1.59] / 66.9MB [5.79] 151.51 ms [1.10] / 28.3MB [2.45]

表三：事务（三方言，仅最小档）

胜场：ADO 8 · PalORM 6 · Dapper 1 · FreeSql 0

操作 测什么 总评
TxSingleInsert 事务内单行插入 四臂持平（事务开销主导）
TxHundredInserts 事务内 100 行逐条插入 联网方言接近；FreeSql SQLite 明显偏慢（逐行表达式开销放大）
TxBulkInsert 事务内批量插入 PalORM 贴地板；Dapper（multi-exec 无语句缓存复用）与 FreeSql 明显偏慢
TxRollback 事务回滚（更新后显式 Rollback） 联网方言接近；SQLite FreeSql 明显偏慢
EnumInserts 枚举列事务内逐条插入（Status TEXT 列） PalORM 贴平（SQLite 略高为每调用会话契约成本，已探针定案）；FreeSql 全方言明显偏慢，Dapper SQLite 偏慢

SQLite

操作 档 🏆 ADO.NET PalORM Dapper FreeSql
TxSingleInsert 2000 ADO 18.9 µs [1.00] / 3.9KB [1.00] 19.6 µs [1.03] / 4.3KB [1.09] 19.6 µs [1.04] / 4.7KB [1.20] 32.4 µs [1.71] / 7.0KB [1.78]
TxHundredInserts 2000 🏆 PalORM 185.7 µs [1.00] / 137KB [1.00] 185.4 µs [1.00] / 92.7KB [0.68] 254.3 µs [1.37] / 220KB [1.61] 1.51 ms [8.11] / 541KB [3.96]
TxBulkInsert 2000 ADO 2.54 ms [1.00] / 1.7MB [1.00] 2.56 ms [1.01] / 1.7MB [1.00] 4.50 ms [1.77] / 4.3MB [2.48] 7.51 ms [2.96] / 3.5MB [2.02]
TxRollback 2000 ADO 569.8 µs [1.00] / 435KB [1.00] 631.5 µs [1.11] / 437KB [1.01] 2.20 ms [3.86] / 1.6MB [3.74] 7.55 ms [13.26] / 3.5MB [8.16]
EnumInserts 2000 ADO 129.9 µs [1.00] / 59.0KB [1.00] 149.2 µs [1.15] / 59.1KB [1.00] 365.1 µs [2.81] / 223KB [3.77] 1.25 ms [9.58] / 497KB [8.42]

MySQL

操作 档 🏆 ADO.NET PalORM Dapper FreeSql
TxSingleInsert 2000 Dapper 4.48 ms [1.00] / 21.1KB [1.00] 4.43 ms [0.99] / 22.2KB [1.05] 4.42 ms [0.99] / 25.6KB [1.21] 4.54 ms [1.01] / 26.9KB [1.27]
TxHundredInserts 2000 🏆 PalORM 25.70 ms [1.00] / 368KB [1.00] 24.46 ms [0.95] / 301KB [0.82] 25.16 ms [0.98] / 348KB [0.94] 27.74 ms [1.08] / 811KB [2.20]
TxBulkInsert 2000 🏆 PalORM 11.64 ms [1.00] / 485KB [1.00] 11.56 ms [0.99] / 490KB [1.01] 27.22 ms [2.34] / 6.7MB [14.07] 20.97 ms [1.80] / 3.4MB [7.22]
TxRollback 2000 ADO 93.37 ms [1.00] / 1.3MB [1.00] 93.93 ms [1.01] / 1.4MB [1.02] 99.58 ms [1.07] / 2.4MB [1.78] 114.81 ms [1.23] / 4.9MB [3.62]
EnumInserts 2000 🏆 PalORM 24.93 ms [1.00] / 286KB [1.00] 24.48 ms [0.98] / 285KB [1.00] 25.80 ms [1.03] / 434KB [1.52] 29.01 ms [1.16] / 772KB [2.70]

PostgreSQL

操作 档 🏆 ADO.NET PalORM Dapper FreeSql
TxSingleInsert 2000 ADO 1.52 ms [1.00] / 8.4KB [1.00] 1.53 ms [1.01] / 9.3KB [1.11] 1.56 ms [1.03] / 8.2KB [0.98] 1.60 ms [1.06] / 12.3KB [1.47]
TxHundredInserts 2000 🏆 PalORM 20.60 ms [1.00] / 314KB [1.00] 20.46 ms [0.99] / 212KB [0.67] 20.91 ms [1.01] / 283KB [0.90] 23.98 ms [1.16] / 703KB [2.24]
TxBulkInsert 2000 🏆 PalORM 4.77 ms [1.00] / 340KB [1.00] 4.75 ms [1.00] / 341KB [1.00] 17.79 ms [3.73] / 6.7MB [20.13] 21.38 ms [4.48] / 3.4MB [10.24]
TxRollback 2000 ADO 102.80 ms [1.00] / 934KB [1.00] 102.91 ms [1.00] / 1.0MB [1.11] 105.76 ms [1.03] / 1.7MB [1.88] 122.72 ms [1.19] / 4.4MB [4.85]
EnumInserts 2000 ADO 19.86 ms [1.00] / 163KB [1.00] 20.26 ms [1.02] / 184KB [1.13] 20.51 ms [1.03] / 280KB [1.72] 23.45 ms [1.18] / 660KB [4.05]

表四：跨方言 PalORM/ADO 比值（批量族 + GetAllAsync；裸比值，越线 📌）

操作 档 SQLite PostgreSQL MySQL
BulkInsert 2000 1.01 1.04 0.98
BulkInsert 20000 1.03 1.02 1.02
BulkUpdate 2000 1.00 1.03 0.89
BulkUpdate 20000 0.99 0.89 1.00
BulkDelete 2000 0.99 📌0.65 1.00
BulkDelete 20000 0.97 📌0.44 0.94
UpsertBatch 2000 1.01 📌0.51 0.97
UpsertBatch 20000 1.03 📌0.60 1.06
GetAllAsync 2000 0.99 0.99 1.00
GetAllAsync 20000 1.00 1.00 0.99

📦 安装

三个 Provider 包任选其一，每个都自动携带 PalORM.Core（运行时）与 PalORM.SourceGen（编译时源生成器）。 环境要求：.NET SDK 11.0.100-rc.2 或更高（global.json 已锁定 rollForward: disable）；IDE 需支持 Roslyn 源生成器（SourceGen 以 Microsoft.CodeAnalysis 5.9.0 构建）。Native AOT 发布另需约 4 GB 内存（ILC 编译器），详见开发。


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

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

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

每个 Provider 包含 PalORM.Core（运行时）和 PalORM.SourceGen（编译时源生成器）。安装后用下方快速开始的最小示例验证：能创建会话并完成一次插入即安装成功。

数据库兼容性

数据库 版本 驱动 加密
PostgreSQL 14+（推荐 18） Npgsql 10.0.3 SSL/TLS
MySQL 8.0+（推荐 8.4 LTS） MySqlConnector 2.6.2 SSL/TLS
SQLite 3.54+（via SQLite3MC 2.6.1） Microsoft.Data.Sqlite.Core 11.0.0-rc.2 AES-256（驱动层，Password=）

🚀 快速开始

五步跑通：定义实体 → 创建会话 → 建表种子 → CRUD → 批量操作。所有片段可直接组合成最小可运行程序。

定义实体

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; }
}

可空约定：引用类型属性声明为非可空（如 string Email）而库里是 NULL 时，读取抛 SqlNullValueException（响亮失败，不返回 null、不出静默错数据）。可能存 NULL 的列请声明为可空（string?）。替代方案评估留档于 docs/性能优化方案-step7-pg-master.md T13。

创建会话

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

可选：启动期预热连接池（v5.6.0），让首批突发查询命中暖连接而非各付一次建连（远程建连实测约 8.5 ms/条）：

// 打开 N 条连接随即归还池；SQLite 无池直接返回。建议配合 MinPoolSize 保持暖态
await DataSession<PostgreSqlProvider>.PreWarmAsync(options, count: 10);

会话复用优先：同一作用域（请求、批处理循环）内请复用一个 db 会话跑多次操作，而不是每操作新建。会话内同形状操作自动晋升命令复用槽（第 3 次起复用命令对象与参数槽），且避免每次重新 prepare——Microsoft.Data.Sqlite 的预备语句缓存按命令实例生效（官方源码确认：换命令即重新 sqlite3_prepare_v2 并额外分配一段 SQL 字节缓冲）。复用形态下每操作省下会话构造（约 632 B，2026-10-14 W3 后探针）与重复准备成本；单次即弃的写法（每操作 CreateAsync）适合低频调用，高频热路径建议复用。

建表与种子

// 执行编译期生成的三方言建表 DDL（幂等：已存在对象自动跳过；FK 按依赖拓扑序建表）
await db.MigrateAsync();

// 种子数据：稳定主键事务内幂等 Upsert，重复执行不重复插入
await db.SeedAsync(new[] { new User { Id = 1, Email = "admin@example.com", CreatedAt = DateTime.UtcNow } });

// 对照实体声明检查数据库缺列（返回缺失列清单，升级/对账用）
List<string> missing = await db.ValidateSchemaAsync<User>();

CRUD

// 插入（PG/SQLite RETURNING / MySQL LAST_INSERT_ID 自增回填）
var user = await db.InsertAsync(new User { Email = "alice@example.com", CreatedAt = DateTime.UtcNow });

// 查询
var alice = await db.GetAsync<User>(user.Id);   // 单键直查：首选专用 API
var all = await db.From<User>().Where($"email LIKE {"%@example.com%"}").ToListAsync();

// 更新（乐观锁实体自动校验版本，冲突抛 ConcurrencyConflictException）
alice.Email = "new@example.com";
await db.UpdateAsync(alice);

// 插入或更新（默认主键走 Insert，非默认主键单行 UPSERT）
await db.SaveAsync(alice);

// 删除（软删实体自动转 UPDATE deleted_at，否则物理 DELETE）
await db.DeleteAsync<User>(alice.Id);

单键直查用 GetAsync，不要用链式等价写法：GetAsync 为单键设计（SQL 常量缓存、单行直读、不经查询构建器与列表物化），同口径实测比 From<T>().Where(Id==x).FirstOrDefaultAsync() 省约 880 B/操作且快 25~30%（2026-10-01 探针，3000 次摊销）。带过滤条件的查询才用 From<T>() 链式。

批量操作

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

// 批量更新（乐观锁实体：PG/MySQL 自动走版本化单语句，能力不全回退 DbBatch）
await db.BulkUpdateAsync(users);

// 批量更新（v5.0 单语句批量）
await db.BulkUpdateBatchAsync(users);

// 批量删除（PG: = ANY(数组) 单语句 / SQLite: json_each 单参数服务端展开 / MySQL: IN 分批单语句，满批命令与参数池化复用）
await db.BulkDeleteAsync<User>(keyList);

// 批量 UPSERT（多行 UPSERT 单语句；默认键新行走逐条 INSERT 回填自增 ID）
await db.BulkMergeAsync(users);

各方法按方言的 SQL 策略：

方法 PG MySQL SQLite
BulkInsertAsync Binary COPY BulkCopy（local_infile）或多值 INSERT 行预编译批量
BulkUpdateAsync 版本化单语句 + 乐观锁（能力不全回退 DbBatch） 版本化单语句 + 乐观锁（能力不全回退 DbBatch） 逐条 + 乐观锁
BulkUpdateBatchAsync FROM VALUES UPDATE JOIN VALUES ROW（8.0.19+，低版本回退 CASE WHEN） 自动回退逐条
BulkDeleteAsync = ANY(数组) 单语句 IN 分批单语句 json_each 单参数服务端展开
BulkMergeAsync 多行 UPSERT（ON CONFLICT DO UPDATE） 多行 UPSERT（ON DUPLICATE KEY UPDATE） 行预编译 UPSERT（ON CONFLICT DO UPDATE，单行语句缓存复用）

BulkMergeAsync（v5.6.0 集合化）按键状态分区：默认键（新行）走逐条 INSERT 保留 ID 回填契约，非默认键行 PG/MySQL 按方言参数上限分批走多行 UPSERT（PG 与 MySQL 65535 参数上限，MySQL ODKU 单批 1000 行），SQLite 走行预编译 UPSERT（单行语句缓存复用，免参数上限分批）；[ConcurrencyCheck] 实体维持逐条（UPSERT 无法尊重乐观锁）。

📖 使用

查询与分页、聚合与流式、事务与弹性、横切关注点、原生 SQL 与存储过程、Scaffold 工具、批量选型与形态选型。

查询与分页

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

同会话并发执行多个查询前先声明并行读租约：

await using (db.ForParallelReads())
{
    await Task.WhenAll(db.From<User>().ToListAsync(), db.From<Order>().ToListAsync());
}

并行读作用域：From<T>() 查询族与 GetAsync 单行直查族在 ForParallelReads() 内都走作用域局部读连接池（各自独立连接，上限 8，查询结束归还）；与在飞只读操作并发的写/事务/Bulk 会被单活动门禁拒绝。流式消费大结果集用 QueryAsyncEnumerable<T>（await foreach），避免全量物化的内存峰值；Include 只生成 JOIN 不装配导航，需按父分组时自行配对或直接流式处理。

内存与 GC 选型

  • 结果集形态：ToListAsync 全量物化（List<T> 初始容量按会话内上次行数自适应，重复查询同表零扩容拷贝）；行数不可控的大表用 QueryAsyncEnumerable<T> 流式（每行即时消费，峰值内存 O(1)）。
  • 查询缓存：WithCache 按查询 opt-in（默认关）；未注入 DbOptions.QueryCache 时使用进程级共享默认实例（1024 条，多租户靠 __t:{tenantIdLength}:{tenantId}: 前缀隔离，IgnoreFilters 走独立 __all__:），需要按租户控制容量/TTL 时注入独立实例；TTL 最终一致，写后读一致用 db.EvictQueryCache() 显式收窄。
  • GC 模式：高吞吐服务端（多核 + 大堆）建议 <ServerGarbageCollection>true</ServerGarbageCollection>（Gen0 分配缓冲更大、GC 频率降）；容器配 GarbageCollectionHeapHardLimit（如 75c00000=2GB）防OOM；客户端/小内存场景保持 Workstation 默认。基准口径为 Workstation（docs/性能基准规范.md §4.1），Server GC 下分配数字不变、GC 频率与暂停分布不同。

Keyset 游标分页

大偏移量场景比 OFFSET 稳定，返回行列表与总数：

// 第一页：按 CreatedAt 降序取 20 行
var (rows, total) = await db.From<Order>().ToPageAsync(20, o => o.CreatedAt);

// 下一页：上一页末行的排序值作游标
var next = await db.From<Order>().ToPageAsync(20, o => o.CreatedAt, lastValue: rows[^1].CreatedAt);

聚合五函数

软删除与租户过滤自动生效：

long count = await db.CountAsync<Order>($"status = {OrderStatus.Paid}");
decimal sum = await db.SumAsync<Order>(o => o.Amount);
double avg = await db.AvgAsync<Order>(o => o.Amount);
DateTime? latest = await db.MaxAsync<Order, DateTime>(o => o.CreatedAt);

流式消费大结果集

两种形态都不物化整表 List<T>，峰值内存 O(1)：

// 回调式：逐行消费，不建列表
await db.From<Order>().ForEachAsync(order => sink.Write(order));

// 异步枚举式：await foreach 消费原生 SQL 结果
await foreach (var order in db.QueryAsyncEnumerable<Order>($"SELECT * FROM orders WHERE status = {status}"))
    sink.Write(order);

多结果集（GridReader）：

await using var grid = await db.From<User>()
    .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();

事务与弹性

函数式事务 WithTransaction(callback) 自动 commit/rollback，支持保存点：

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);
});

事务级瞬时错误重试

（整事务按方言错误码重放，at-least-once 契约：PG 40001/40P01、MySQL 1213/1205、SQLite BUSY/LOCKED）；保存点与外部事务接入：

// 事务重试：死锁/锁超时整事务重放（回调须幂等）
await db.WithTransactionRetry(async ct => await db.BulkInsertAsync(items, ct: ct));

// 保存点：长事务内部分回滚
await using var tran = await db.BeginTransactionAsync();
await db.InsertAsync(order);
await db.SavepointAsync(tran, "sp1");
await db.ExecuteAsync($"UPDATE ...");           // 失败则只回滚到 sp1
await db.RollbackToAsync(tran, "sp1");
await tran.CommitAsync();

// 外部事务接入（外部 Dispose 后本会话续用会响亮失败，不静默自动提交）
db.UseTransaction(externalTran);

// 隔离级别：会话级设定，后续 BeginTransactionAsync 默认取用
db.WithIsolationLevel(IsolationLevel.ReadCommitted);
await using var tran = await db.BeginTransactionAsync();

弹性策略（WithRetry 指数退避 + WithCircuitBreaker 熔断）自 v5.4 起自动覆盖只读查询管线：

// Production 预设已含弹性（MaxRetries=5 / 熔断阈值 10 / 半开 60s / 作用域 Process）
await using var db = await DataSession<PostgreSqlProvider>.CreateAsync(
    DbOptions.Production(connectionString));

// 需要自定义阈值时在会话上链式覆盖（方法在 DataSession 上，返回同一会话）
db.WithRetry(maxRetries: 3)
  .WithCircuitBreaker(failureThreshold: 5, resetAfter: TimeSpan.FromSeconds(30));

// SELECT 瞬时故障（死锁/超时/连接闪断）自动重试；非幂等写入不自动重试，显式声明弹性意图：
long affected = await db.ExecuteWithResilience(
    token => db.From<Order>()
        .Set(o => o.Status, OrderStatus.Paid)
        .Where($"id = {orderId}")
        .ExecuteNonQueryAsync(token), ct);
路径 弹性覆盖 说明
From<T>() SELECT 族、GetAsync/GetAllAsync、聚合 自动 瞬时故障按配置重试并计入熔断
连接建立 自动 CreateAsync 自有重试循环
写入路径（Insert/Update/Delete/Save/Bulk/存储过程） 直连 非幂等写自动重试有重复执行风险；显式需求用 ExecuteWithResilience
事务内查询 / ToPageAsync / 原始 SQL 家族 直连 事务内重试以次生异常掩盖根因

只读查询走弹性策略的每查询常数开销约 272 B 分配，与结果行数无关（单行 +8%，千行 +0.2%）；MaxRetries=0 + CircuitBreakerThreshold=0 可完全直通，代价是失去带 PalORM.InfrastructureTimeout 标记的超时异常。

PG 事务级咨询锁（TryAcquireXactLockAsync 为非阻塞变体；必须在事务内调用，事务外获取会立即释放并显式报错）：

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

横切关注点

// 审计拦截器（v5.0）：logParameters:true 时 [SensitiveData] 列参数值自动掩码
var db = await DataSession<PostgreSqlProvider>.CreateAsync(new DbOptions
{
    ConnectionString = connectionString,
    Interceptors = [new AuditInterceptor(loggerFactory.CreateLogger("Audit"))],
    SessionSetupSql = "SET TIME ZONE 'UTC'; SET search_path TO 'app, public'"
});

⚠️ AuditInterceptor 覆盖面：实体 SELECT 管线、QueryBuilder UPDATE 与 ExecuteAsync（v5.6.0 接入）；InsertAsync/DeleteAsync/SaveAsync/Bulk 家族/存储过程/迁移不产生审计记录，完整写入审计请用数据库层审计或 OpenTelemetry。

其余横切能力：[SoftDelete] 自动 WHERE 过滤、[TenantAware] + WithTenant(id) 单库列隔离（缓存 key 自动加 __t:{tenantIdLength}:{tenantId}: 前缀，IgnoreFilters() 走独立 __all__: 命名空间）、[ConcurrencyCheck] 乐观锁、ForRead 读写分离。全部注解（23 个）与执行方法明细见 docs/API参考.md。

原生 SQL 与 SQL 文件

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

SQL 文件编译时嵌入、校验存在性并按需提取方言段：

public static partial class Reports
{
    [SqlFile("Reports/MonthlySales.sql")]
    public static partial string MonthlySales();

    // Provider = "pg" 只提取文件内 -- @pg 方言段
    [SqlFile("Reports/Sales.sql", Provider = "pg")]
    public static partial string SalesPg();
}

// MonthlySales() 返回编译期嵌入的 SQL 文本（生成器校验文件存在），交由 QueryAsync / ScalarAsync 等执行

[SqlTemplate] 把方法体插值串提升为模板常量（方法须无参非泛型，插值洞只引用静态可解析符号），重复执行的 SQL 免每次字符串构造，配合查询构建器 .AsPrepared() 走 DbCommand.PrepareAsync 预编译：

public static class UserQueries
{
    [SqlTemplate("ActiveUsers")]
    public static FormattableString ActiveUsers()
        => $"SELECT * FROM users WHERE active = 1 AND deleted_at IS NULL";
}

// 模板方法返回 FormattableString，直接交给原生 SQL 族执行
var users = await db.QueryAsync<User>(UserQueries.ActiveUsers());

PG 专有：WhereJson（JSONB 路径查询）、PgNotificationListener（NOTIFY/LISTEN 异步监听，自动重连）、NotifyAsync（参数化 pg_notify() 发送）。

存储过程与健康检查

// 存储过程：强类型输入/输出参数，过程名白名单校验，single-use 契约
var sp = db.StoredProc("sp_transfer_stock")
    .WithParam("from_sku", fromSku)
    .WithParam("qty", qty)
    .WithOutputParam<int>("rows_affected");
int affected = await sp.ExecuteAsync(ct);            // 返回受影响行数
int? moved = sp.GetOutputValue<int>("rows_affected"); // 输出参数强类型取回

// 存储过程结果集直接物化
List<StockRow> rows = await sp.QueryAsync<StockRow>(ct);

// 健康检查：SELECT 1 探活（错误消息只透出异常类型名，防数据库拓扑泄露）
HealthResult health = await db.HealthCheckAsync();

// 唯一键冲突跨方言统一翻译（不用记各驱动错误码）
try { await db.InsertAsync(user); }
catch (UniqueConstraintViolationException) { /* 邮箱已注册 */ }

// 乐观锁冲突（[ConcurrencyCheck] 实体 UpdateAsync 版本不匹配时）
try { await db.UpdateAsync(order); }
catch (ConcurrencyConflictException) { /* 重新读取合并 */ }

需要驱动原生能力时 db.GetRawConnection() 返回底层 DbConnection 逃生舱。

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）。

批量 API 选型速查

场景 用 不用 理由
批量插入，不需要 ID 回填 BulkInsertAsync 逐条 / SessionBatch 方言最快路径（COPY / LOAD DATA / 行预编译），实测事务内 100 行比逐条快 8.4×
批量插入且需逐行回填自增 ID BulkMergeAsync（默认键走逐条回填）或 SessionBatch BulkInsertAsync COPY / LOAD DATA 不回填 ID
混合语句或需逐条语义控制 SessionBatch（DbBatch 打包） 逐条往返 单往返打包多语句，SQLite 20 条/批
按非主键列批量更新（每行不同值） BulkUpdateBatchAsync 逐条 单语句多行 SET（PG FROM VALUES / MySQL JOIN VALUES ROW）
乐观锁实体批量更新 BulkUpdateAsync BulkUpdateBatchAsync 版本化单语句（PG UNNEST / MySQL JOIN VALUES ROW）逐行校验版本；能力不全回退 DbBatch
插入或更新（键存在则更新） BulkMergeAsync 手写 ON CONFLICT 租户实体自动限定本租户（跨租户命中 0 行）
大键集删除（万级以上） BulkDeleteAsync 逐条 Delete SQLite json_each 单参数免参数上限分批 / PG = ANY 数组 / MySQL IN 按上限分批，整批单事务，参数对象批间复用

按形态选 API：会话池与批量路径

同一 API 在不同使用形态下的表观开销构成不同，按形态选对入口的收益大于任何库内微优化。

场景 入口 关键收益
一请求一会话（Web/API） DataSessionPool.RentAsync 复用槽跨租期激活；租还约 1 µs
高吞吐逐行写 BulkInsertAsync / BulkUpdateBatchAsync 会话/命令成本摊到 1/N
大结果集 / 无界流 QueryAsyncEnumerable<T> 恒定内存，每行分配更低
单键查询 GetAsync 直查槽 + 单行物化
分页 ToPageAsync 单往返分页（PG COUNT+页 SELECT 打包）

下面按场景展开；批量选型见上方“批量 API 选型速查”。

一请求一会话（Web/API 服务）用会话池（v6.5 DataSessionPool，API 细节见API 参考 · 会话池）：

// 启动时创建一次（maxIdleSize 按峰值并发调整）
var pool = DataSessionPool<PostgreSqlProvider>.Create(options, maxIdleSize: 16);

// 每请求：租出即用，DisposeAsync 即归还
await using var db = await pool.RentAsync();
var user = await db.GetAsync<User>(id);

归还时瞬态状态（租户/超时/重试等 With* 覆写、拦截器加项）全部复位（租期加项一并释放；池基准拦截器由调用方持有）；租出时对脏会话复位连接级会话态（PG RESET ALL; RESET ROLE / MySQL COM_RESET_CONNECTION）并重放 SessionSetupSql；空闲超过 PoolConnectionValidationInterval（默认 30s）的会话先 SELECT 1 探活、失败换新，命令复用槽、读连接、物化容量跨租期保留——复用槽在"一请求一会话"形态下不经池化永不激活（同形状第 3 次操作才晋升）。32 并发压测实测：P99 −18%、Gen0 回收 −58%、每操作分配 −2576 B；池化形态单键直查 P/ADO 比值 MySQL 0.99 / PG 0.87（台账批），租还自身约 1 µs。

DI 容器场景把 IDataSessionFactory<TProvider> 注册为单例即可，不依赖额外容器包：

var factory = new DataSessionFactory<PostgreSqlProvider>(options, maxIdleSize: 16);
services.AddSingleton<IDataSessionFactory<PostgreSqlProvider>>(factory);

// 每请求（scoped 服务的构造/方法内）
await using var db = await factory.RentAsync(ct);

高吞吐逐行写换批量 API，不要在逐条循环里找损耗。逐条 UpdateAsync 每行各付一次会话门禁与命令往返；合成单语句多行（BulkUpdateBatchAsync）或走批量路径（见上方速查表）后，这部分成本摊薄到 1/N。逐条循环里的每行开销是形态决定的，不是可挤的库内水分。

长会话顺序循环的对比数字要读连接态。基准中"每操作新建会话"与"长会话复用"的表观差距主要来自连接/命令冷态与驱动侧成本：库侧单键执行成本已与 ADO 地板重合（见性能），评估自身业务收益时以同形态对照为准。

✅ 最佳实践速查

按使用频率收拢，详细依据见各链接位置：

会话与连接

  • 同一作用域复用一个 DataSession，不要每操作 CreateAsync（会话内同形状操作第 3 次起自动复用命令与参数槽）
  • Web/API"一请求一会话"部署用 DataSessionPool（启动建池、RentAsync 租用、DisposeAsync 归还）：复用槽跨租期保留是池化的核心收益，不池化则该形态下永不激活
  • 启动期预热连接池 PreWarmAsync（远程建连实测约 8.5 ms/条），配合 MinPoolSize 保持暖态
  • 高频单键查询用 GetAsync（比链式等价写法快 25~30%、省 880 B）；带过滤条件才用 From<T>()
  • 只读副本配置 ReadConnectionString 后，报表/列表查询显式 .ForRead()，主从延迟敏感的强读留在主库
  • 并发查询先声明 await using (db.ForParallelReads())；作用域内 GetAsync 与查询族走作用域局部读连接池（上限 8）；与在飞读并发的写操作会被门禁拒绝
  • 跨程序集模型报 "not registered"：各模型程序集经 ModuleInitializer 在首次被触达时注册，确保实体类型被真实引用（类型实例化/成员调用均算触达）

查询与结果集

  • 行数不可控的大表用 QueryAsyncEnumerable<T> 流式消费（峰值内存 O(1)），不要 ToListAsync 全量物化
  • 深翻页用 ToPageAsync 游标（Keyset），不要大 OFFSET（扫描量随偏移线性增长）
  • 大键集过滤用 WhereIn/WhereNotIn（自动按 500 键分批、空集安全恒假；总绑定参数仍受方言上限约束，SQLite 999 / 通用 65535，超限会提前抛 ArgumentException，更大的键集用临时表 JOIN）
  • 热路径的 OrderBy/Select 表达式提到静态字段（每棵树 512 B + 0.5~1.6 µs 的调用点成本可消除）
  • 排查 SQL 用 AsDryRun()/ToSql 预览（SQL + 参数，不执行）；生产定位慢查询可开 AutoTagging（PalORMAutoTagging 编译开关，SQL 自动注入「文件:行号 成员」注释）
  • Include/ThenInclude 只生成 JOIN 不装配导航（按父分组自行配对）；列裁剪物化用 [Projection] DTO + QueryAsync<T>（大结果集用 struct 投影 + QueryStructsAsync<T>；Select 投影仅 DryRun/ToSql 支持）
  • WithCache 默认关；启用后写后读一致用 db.EvictQueryCache() 显式收窄

写入与批量

  • 批量 API 按上方选型速查表选择；不要在循环里逐条 InsertAsync（连接往返是数量级差异）
  • 唯一键冲突捕获 UniqueConstraintViolationException（跨方言统一翻译，不用记驱动错误码）；乐观锁冲突捕获 ConcurrencyConflictException（重读数据合并后重试）
  • [ConcurrencyCheck] 实体不要调 BulkUpdateBatchAsync（显式单语句 API 不承载逐行版本谓词，PALORM031 编译期已拦），批量更新走 BulkUpdateAsync（自动路由到版本化单语句，能力不全回退 DbBatch）
  • BulkInsertAsync 不回填自增 ID（COPY / LOAD DATA 契约）；需逐行回填用 BulkMergeAsync（默认键走逐条）或 SessionBatch
  • 可能存 NULL 的列声明可空属性（string?），非可空遇 NULL 会响亮抛 SqlNullValueException（不出静默 null）
  • 敏感列标 [SensitiveData]（Set() 写入该列的参数值在审计日志中掩码；Where 手写 SQL 的洞值无列映射，不掩码）；非幂等写不要指望自动重试（写入路径直连语义），确需弹性用 ExecuteWithResilience 包裹并自行评估重复执行风险

事务

  • 事务内批量优先 BulkInsertAsync 而非 SessionBatch（同事务 100 行 5.4ms vs 16.8ms）
  • 事务内查询 / 原始 SQL 不自动重试（重试会以次生异常掩盖根因）；确需事务级容错用 WithTransactionRetry（方言瞬时错误码整事务重放），回调必须幂等（at-least-once 契约）
  • 不支持嵌套事务（重复 BeginTransactionAsync 响亮抛异常）；长事务内部分回滚用保存点 SavepointAsync/RollbackToAsync
  • 外部事务经 UseTransaction 接入后，外部已 Dispose 再用本会话会响亮失败（不静默自动提交）

多租户与横切

  • [TenantAware] 实体会话创建后立即 WithTenant(id)，不要延后到首个查询（缓存 key 前缀随租户切换失效）
  • InsertAsync/BulkInsertAsync/BulkMergeAsync 不附加租户谓词，tenant_id 必须由调用方赋值（PALORM040 只拦可空列）；租户列在 Update/BulkUpdate 与 UPSERT 冲突更新中不可写（防跨租户搬移），确需迁移用原生 SQL
  • 需要跨租户管理查询时用 IgnoreFilters()；该调用把会话切到全量视图且当前无公开复位 API，管理查询结束请换一个会话（池化会话归还后重租即可），不要在同一个会话里继续做租户过滤查询
  • AuditInterceptor 覆盖面 = 实体 SELECT 管线 / QueryBuilder UPDATE / ExecuteAsync；InsertAsync/DeleteAsync/Bulk 族/存储过程不产生审计记录，完整写入审计用数据库层审计或 OpenTelemetry
  • PG 连接串调优 NoResetOnClose=true 下 raw SQL 的 SET/临时表跨池租客可见（ITM-652）：需要隔离时用独立连接（Max Pool Size=1）或显式 DISCARD

AOT 与部署

  • [OwnedJson] 对象形态必须配 System.Text.Json 源生成 JsonSerializerContext（AOT 安全的硬要求，缺失编译期报 PALORM008-010）
  • 高吞吐服务端开 <ServerGarbageCollection>true</ServerGarbageCollection>；容器配 GarbageCollectionHeapHardLimit 防 OOM（Server GC 下分配数字不变、GC 频率与暂停分布不同）
  • 只部署单方言时可设 MSBuild 属性 PalORMTargetDialects 裁剪 CRUD SQL 发射面（DDL 恒全方言）；AOT 发布需约 4 GB 内存（ILC 编译器）

运维与排查

  • 生产用 DbOptions.Production（已含弹性/连接池预设），只覆盖确需自定义的项
  • 一请求一个 DataSession 的短会话部署：Production 预设已默认 CircuitBreakerScope.Process（熔断跨会话累计，数据库持续故障时快速失败）；自建 DbOptions 的等价部署请显式设 CircuitBreakerScope.Process，Session 级计数随会话销毁、短会话下阈值几乎不可能达到
  • 健康检查端点接 HealthCheckAsync（SELECT 1 探活，错误消息只透出异常类型名，防数据库拓扑泄露）
  • 可观测性接 OTel：WithTracing + WithMetrics（指标族 palorm.query.executions/palorm.query.duration，查询缓存另有 palorm.cache.* 四指标）
  • 超时异常带 PalORM.InfrastructureTimeout 标记的属基础设施侧（网络/服务器），先查环境再查代码；瞬时故障判定用 Data["PalORM.IsTransient"] 标记
  • MySQL 批量写报 ER_NET_PACKET_TOO_LARGE 先查服务端 max_allowed_packet；LOAD DATA 回退多值 INSERT 是 local_infile 关闭时的预期行为（非错误）

🔧 配置

三预设起步（Development / Production / Testing），24 项配置按需覆盖；三方言连接串自动调优仅补默认、不覆盖显式设置。

预设配置

var dev  = DbOptions.Development(connectionString);            // 开发环境
var prod = DbOptions.Production(connectionString, readConn);  // 生产（含连接池 + 读写分离）
var test = DbOptions.Testing(connectionString);               // 测试（零重试 + 短超时）
var env  = DbOptions.FromEnvironment("PALORM_CONNECTION");    // 环境变量（Docker/K8s 友好）

FromEnvironment 支持的环境变量：PALORM_CONNECTION（必需）、PALORM_READ_CONNECTION、PALORM_COMMAND_TIMEOUT、PALORM_CONNECTION_TIMEOUT、PALORM_MAX_RETRIES、PALORM_CIRCUIT_BREAKER_THRESHOLD、PALORM_MAX_POOL_SIZE；组装后自动 Validate()，非法值在启动期报错。

配置项

连接与池

属性 类型 默认值 说明
ConnectionString string（必需） — 主库连接串，支持 $ENV:VAR 环境变量引用
ReadConnectionString string? null 只读副本连接串，配置后 ForRead() 自动路由
MaxPoolSize int 100 连接池上限（SQLite 忽略）
MinPoolSize int 0 池内保底暖连接数（0=驱动默认）
PoolIdleTimeoutSeconds int 0 空闲连接超时秒数（0=驱动默认）
PoolLifetimeMinutes int 60 连接最大生命周期，到期强制重建
PoolConnectionValidationInterval TimeSpan 30s 池化租出探活间隔（0=关闭）

超时 · 重试 · 熔断

属性 类型 默认值 说明
ConnectionTimeout TimeSpan 15s 连接建立超时（含重试）
CommandTimeout TimeSpan 30s 命令执行超时；亚秒值向上取整为 1 秒
MaxRetries int 3 瞬时故障最大重试次数（0=禁用，上限 10；只覆盖读管线）
RetryBackoff Func<int, TimeSpan>? 100→200→400ms 自定义重试退避（参数=重试次数）
OverallDeadline TimeSpan Zero（不设） 整次操作总预算，到期停止重试并抛超时
CircuitBreakerThreshold int 5 连续失败阈值（0=禁用熔断）
CircuitBreakerResetAfter TimeSpan 30s 熔断后半开等待时间
CircuitBreakerScope CircuitBreakerScope Session 熔断作用域（Session/Process，见注）

会话与行为

属性 类型 默认值 说明
SessionSetupSql string? null 主连接首次激活后执行的 SQL（分号分隔）
ReadSessionSetupSql string? null 读副本连接的同类设置（每会话一次）
Interceptors IReadOnlyList<IQueryInterceptor>? null 查询拦截器，按 Priority 升序执行
ValidateQueryColumnOrder bool true QueryAsync 首行列序校验（别名列需关闭，见注）
UseSynchronousRowRead bool false 物化读走同步 Read()（MySQL 建议开启，见注）
PrepareCacheSize int 100 PG AutoPrepare 缓存容量（0=禁用；其余方言忽略）
PrepareThreshold int 2 PG 同 SQL 自动预编译阈值（最小 1；其余方言忽略）
QueryCache IQueryCache? 1024 条 查询缓存（默认进程级共享）
LoggerFactory ILoggerFactory? null 设置后 DataSession 创建 ILogger

注（机制细节）：

  • OverallDeadline：不设时最坏墙钟 ≈ (MaxRetries+1)×CommandTimeout+Σ退避（默认配置约 120 秒）；取值应大于单次 CommandTimeout。
  • CircuitBreakerScope：Session 的失败计数随会话销毁（长会话可用）；Process 按 (Provider, 连接串, 阈值, 冷却) 跨会话累计，一请求一会话的短会话部署必选 Process，否则熔断形同虚设（Production 预设已默认 Process）。
  • MinPoolSize / PoolIdleTimeoutSeconds：0=保留驱动默认（Npgsql 300s / MySqlConnector 180s），正数才覆盖；消除突发查询重建连接的延迟尖峰，代价是空闲超时后首个查询需重建物理连接（跨网段实测 SELECT 1 池内 0.3ms vs 新建 13.5ms；IdleTimeout 自 v5.6.0 起默认 0）。
  • RetryBackoff：默认退避含 50~100% 抖动；负值抛异常。
  • UseSynchronousRowRead：MySQL 实测约 998 vs 1846~2043 ns/行；SQLite 因进程内引擎恒同步；流式 API 始终异步；高并发服务端请先做线程池压力验证。
  • ValidateQueryColumnOrder：用列别名/表达式列时需关闭。
  • QueryCache：注入独立实例实现会话/租户级隔离（需线程安全）。

SQLite 并发写扩展性（2026-09-21 实测）：80/20 读写混合负载下，SQLite 从 1 到 8 线程吞吐下降 69%（WAL 单写者模型，裸 ADO.NET 对照同为 −69%，非 PalORM 引入的锁）；同期 PostgreSQL +7.2×、MySQL +4.6×。高并发写场景选 PG/MySQL，SQLite 适合读密集或低并发写的嵌入式场景。详见 docs/架构设计.md。

连接串自动调优

CreateConnection 时自动调优，仅当用户未显式设置时覆盖默认值。

PostgreSQL（6 项）：

参数 默认 → 调优值 收益
MaxAutoPrepare 0 → 100 自动预编译，查询延迟 −30~50%
AutoPrepareMinUsages 5 → 2 第 2 次执行起 Prepare
NoResetOnClose false → true 归还连接跳过 DISCARD ALL，+30% localhost 吞吐
ReadBufferSize 8192 → 16384 大结果集吞吐
WriteBufferSize 8192 → 16384 大值写入吞吐
Enlist true → false 跳过 TransactionScope 检查

MySQL（5 项）：

参数 默认 → 调优值 收益
AutoEnlist true → false 跳过 TransactionScope
ConnectionReset true → false 跳过 COM_RESET_CONNECTION
CancellationTimeout 2 → 5 防连接泄漏
AllowLoadLocalInfile false → true MySqlBulkCopy 前提
ServerRedirectionMode Disabled → Preferred Azure MySQL 直连

SQLite PRAGMA（9 项）：

PRAGMA 默认 → 调优值 收益
busy_timeout 0 → 5000ms 并发写 BUSY 在引擎内等待
synchronous FULL → NORMAL WAL 下安全，减少 fsync
cache_size 2MB → 64MB 读密集型提升
temp_store DEFAULT → MEMORY 临时表走内存
wal_autocheckpoint 1000 → 1000 显式固定防漂移
journal_size_limit -1 → 64MB 防 WAL 无界膨胀拖慢检查点
mmap_size 0 → 256MB 文件库 I/O 加速（:memory: 跳过）
analysis_limit 1000 → 400 约束 optimize/ANALYZE 采样成本
optimize 0 → 0x10002 连接打开时自动统计优化（官方对长生命周期连接的推荐形态，采样成本由 analysis_limit 约束）；仅文件库宽分支——内存库无持久统计面，只读连接写统计面会 SQLITE_READONLY

NoResetOnClose=true 的会话状态泄漏取舍（raw SQL 的 SET/临时表跨池租客可见）见 ITM-652：需要隔离时用独立连接（连接串 Max Pool Size=1）或显式 DISCARD。

进阶配方

SQLite（经 DbOptions.SessionSetupSql 执行，可覆盖上述默认）：

场景 配方 说明
批量/大行负载建库 PRAGMA page_size=16384 须在库首次创建前生效；既有库静默 no-op
读密集 PRAGMA mmap_size=1073741824 提至 1GB（引擎上限 2GB−64KB）
删除密集 PRAGMA secure_delete=OFF 消除删页覆写写放大；已删内容不再清零，加密库上有 forensic 残留
本地弹性直通 MaxRetries = 0 本地 BUSY 已由 busy_timeout 吸收，弹性机构在 RTT≈0 的本地库是净开销；远程库维持默认

PostgreSQL（连接串层显式启用，各有触发条件与取舍）：

场景 配方 说明
本机/同容器 PG Host=/var/run/postgresql Unix domain socket 替代 TCP（Npgsql 官方性能文档）；Host 以斜杠或盘符开头即按 socket 目录解析
GSS 协商长尾削峰 GssEncryptionMode=Disable 实测（2026-09-26，Npgsql 10.0.3 × PG 18.4）中位建连不变，长尾 149ms → ≤21ms；安全策略变更，仅服务端不要求 GSS 加密时使用
非关键表批量写 事务内首条 SET LOCAL synchronous_commit TO off PG 官方 28.4：短事务吞吐的最大应用层杠杆；崩溃丢最近约 600ms 提交（不损数据）。事件日志/缓存类可接受，账务类不可；须显式 opt-in，PalORM 不默认开启

MySQL（服务端/DBA 决策或显式操作）：

场景 配方 说明
计划器统计刷新 ANALYZE TABLE 表名（经 ExecuteAsync） InnoDB 默认 10% 行数变化自动重算，多数场景无需手工；MigrateAsync 不自动跑
批量写提交削峰 innodb_flush_log_at_trx_commit=2（服务端全局变量） 提交只写 OS 缓存不 fsync；崩溃丢最近约 1 秒提交，判据同 PG synchronous_commit=off
锁等待 无需配置 innodb_lock_wait_timeout（默认 50s）+ PalORM 弹性重试（死锁 1213 / 锁超时 1205）两层兜底
批量写报文上限 服务端 max_allowed_packet ≥ 16MB LOAD DATA 与大参数批单包可达数 MB，超限报 ER_NET_PACKET_TOO_LARGE 或静默断连；报此错先查服务端值
批量写 LOAD DATA 开关 服务端 local_infile=ON 缺一即回退多值 INSERT（检测按连接缓存 60s）；本机实测 LOAD DATA 比多值 INSERT 快 1.39×，远程库差距更大（官方基准 4~5× 量级）
事务内多行插入选型 优先 BulkInsertAsync 同一事务 100 行：逐条 45.7ms → BulkInsert 5.4ms（8.44×）→ SessionBatch 16.8ms；需逐条回填自增 ID 或混合语句时才用 SessionBatch
排序/连接内存缓冲 sort_buffer_size / join_buffer_size ≥ 256KB（默认即此值） 远程大结果集 / 百万行级排序 join 先 EXPLAIN 确认无 Using filesort 再按需调（DBA 决策）
隔离级别 RR→RC WithIsolationLevel(IsolationLevel.ReadCommitted) 引擎默认 RR（间隙锁）放大热点行锁竞争；取舍为 MVCC 快照语义变化，属业务决策

🔄 升级指南

按版本倒序排列；数据正确性修复优先阅读对应小节。

从 6.4.x 升级到 6.5.0：查询语义两处修复（结果可能变化）

两项用户可见行为修复，升级前请核对（详见 CHANGELOG）：

  • WHERE/OR 链式优先级（C16）：Where(A).OrWhere(B).Where(C) 此前生成 (A) OR (B) AND (C)（SQL 求值为 A OR (B AND C)，与方法文档承诺的链式形态不符），本版修复为 ((A) OR (B)) AND (C)。混合 Where/OrWhere 链的查询结果可能变化：纯 AND 链、纯 OR 链与 OR 收尾链的 SQL 文本逐字不变，无需动作。WhereIn/WhereNotIn 同受此修复覆盖。升级动作：检索代码中混合 Where/OrWhere 链，确认查询结果符合链式直觉预期。
  • FormattableString 引号内花括号（C17）：引号内 {N}/} 此前被替换或误抛 FormatException（JSON 文本 '{"a":1}' 无法书写），修复后引号内一律原样透传。此前为绕过该缺陷手写拆串的代码可还原为直书 JSON 字面量。

其余为纯新增（会话池 DataSessionPool）与内部性能/修复，无迁移动作。

从 6.3.x 升级到 6.4.0：Production 预设熔断作用域变更

DbOptions.Production 预设自 6.4.0 起显式设 CircuitBreakerScope = Process（此前为 Session）。影响与动因：

  • 变化：使用 Production 预设时，熔断失败计数按 (Provider, 连接串, 阈值, 冷却) 跨会话累计。一请求一会话的部署下，数据库持续故障时请求快速失败（熔断开闸），而非此前每个请求各自重试 5 次再失败、熔断从不触发的虚设形态。
  • 不变：裸 new DbOptions { ... } 默认仍为 Session；长生命周期会话与测试场景零变化。
  • 多租户注意：多租户共用一个连接串时熔断器为租户间共享粒度，需要租户级隔离的部署用独立连接串，或 with { CircuitBreakerScope = CircuitBreakerScope.Session } 显式回退。

从 6.2.x 及更早升级到 6.3.x（数据正确性修复，强烈建议）

6.3.0 修复了 R-UNNESTB：PG auto-prepare × 命令复用槽交互下的批量操作静默错数（影响 5.7.0 ~ 6.2.0 共 7 个版本）；6.3.1 在此之上恢复了 BulkDelete IN 形态的池化性能（20K 键 37 ms 快态带，0.55× 地板，见性能）。R-UNNESTB 触发条件：连接串启用 MaxAutoPrepare（PalORM 默认调优会设为 100，见连接串自动调优）且同一会话执行第 3 个及后续等长批量批次；后果是第 3 批起静默重发第 2 批的参数（批量删除少删行、批量 UPSERT 写错键），无异常无告警。

  • 升级到 6.3.1 即彻底修复（参数对象从建立到释放全程稳定，auto-prepare 缓存引用不再错配）
  • 暂不能升级的止血：连接串显式加 MaxAutoPrepare=0（代价是失去自动预编译的查询延迟收益，Npgsql 默认即 0）
  • 风险面自查：若历史负载满足触发条件，建议对受影响表的批量操作结果做一次对账（行数/键集合核对）

6.3.0 同时包含 PG 三条批量写走数组形态（UPDATE FROM VALUES(...) 的 UNNEST 化与 DELETE ... = ANY(数组)，批量族时延 −40~74%），行为面无破坏。

从 5.x 升级到 6.0

<details> <summary><b>四项破坏性变更（详见 ADR-N）</b></summary>

删除/变更 迁移动作
IRowFactory<T> 接口 无——零实现零消费，若外部代码引用了它（不存在官方用法），删除引用即可
DataSession.DiffAsync<T>() 换用 ValidateSchemaAsync<T>()，需要 [DIFF] 前缀时自行拼接
DbOptions.NamingConvention（含 ApplyNaming） 删除该设置即可——行为从未生效过（列名映射在编译期由 [Table]/[Column] 注解决定）；要改列名用 [Column("...")]
DbOptions.PoolExplicitlyConfigured 无——零读方内部标记；WithPool/PALORM_MAX_POOL_SIZE 行为不变
[Column] 的 Length/Precision/Scale：int? → int（0=未设置） 无——[Column(Length = 64)] 语法在 5.x 从未可编译过（CS0655）；v6.0 起该语法首次真正可用并参与 DDL

破坏性变更全表见 ADR-N：v6.0 破坏性变更汇总。

</details>

完整版本历史见 CHANGELOG.md。

🧰 开发

构建环境、项目结构与注册契约；完整构建路径与提交防线见 CONTRIBUTING.md。

环境要求

维度 JIT 运行时 Native AOT 编译
CPU 架构 x64 / ARM64 x64 已验证（ARM64 未实测），需指定 RID（-r win-x64 / linux-x64）
内存 256 MB 4 GB（ILC 编译器；运行时仅需约 100 MB）
磁盘 50 MB 100 MB，SSD 推荐（ILC 大量临时文件，HDD 编译慢 5-10x）

软件：.NET SDK 11.0.100-rc.2+（global.json 锁定）· C# latest · Windows 10+ / Linux / macOS · Visual Studio 2026 / Rider / VS Code（需支持 Roslyn 源生成器）。

项目结构

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）

跨程序集注册契约：每个模型程序集的生成物通过 ModuleInitializer 在该模块首次被触达（任一成员被调用、类型被实例化、静态字段被访问）时向 PalORM_Runtime 注册。引用了库程序集但从未触达其中任何类型时，该程序集的实体不会注册，运行期表现为 "not registered"：跨程序集消费方请确保实体类型被真实引用。

构建、测试与基准

SQLite 测试开箱即跑（无需外部数据库）；PG/MySQL 集成测试需外部数据库。构建路径、本地提交防线与基准环境（BenchmarkDotNet 本地 fork）见 CONTRIBUTING.md，架构决策见 docs/架构设计.md 与 docs/adr/。

🤝 贡献

欢迎 issue 与 PR。提交前请跑通相关测试套件并保持 0 警告（TreatWarningsAsErrors）；涉及性能的改动请附基准前后对比。详细流程见 CONTRIBUTING.md。

💬 社区

<div align="center">

<img src="docs/qq-group.jpg" width="260" alt="QQ 群二维码：C#/.NET 新技术交流群（群号 1125599744）">

C#/.NET 新技术交流群（群号 1125599744）

QQ 内搜索群号或扫码加入。

</div>

📄 许可证

Apache-2.0

v6.7.0 及以前的已发布版本仍为 AGPL-3.0-only；<br> v6.8.0 及以后的新版本统一变更为 Apache-2.0 发布。

<div align="right">

⬆ 回到顶部

</div>

Product Compatible and additional computed target framework versions.
.NET net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

  • net11.0

    • No dependencies.

NuGet packages (7)

Showing the top 5 NuGet packages that depend on PalORM.Core:

Package Downloads
PalORM.PostgreSql

PalORM PostgreSQL Provider — Npgsql 适配 + JSONB/LISTEN/NOTIFY 扩展
PalORM.MySql

PalORM MySQL Provider — MySqlConnector 适配
PalORM.Sqlite

PalORM SQLite Provider — Microsoft.Data.Sqlite.Core + SQLite3MC 适配
PalDDD.PalORM

Pal.DDD PalORM 持久化适配核心层（真 AOT + 源生成 + 编译期方言特化）— 含 6 Store + UnitOfWork（v54 勘正：对齐 v34 P3 计数勘正）
PalDDD.PalORM.Sqlite

Pal.DDD PalORM SQLite 适配包（AOT + 源生成；FTS5/JSON1 双栈 API，PRAGMA 优化待迁移）

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
6.8.0 153 10/25/2026
6.7.0 152 10/23/2026
6.6.0 130 10/20/2026 6.6.0 is deprecated because it is no longer maintained.
6.5.0 146 10/14/2026 6.5.0 is deprecated because it is no longer maintained.
6.4.1 172 10/11/2026 6.4.1 is deprecated because it is no longer maintained.
6.4.0 127 10/10/2026 6.4.0 is deprecated because it is no longer maintained.
6.3.1 167 10/7/2026 6.3.1 is deprecated because it is no longer maintained.
6.3.0 123 10/6/2026 6.3.0 is deprecated because it is no longer maintained.
6.2.0 143 9/30/2026 6.2.0 is deprecated because it is no longer maintained.
6.1.0 128 9/29/2026 6.1.0 is deprecated because it is no longer maintained.
6.0.1 139 9/28/2026 6.0.1 is deprecated because it is no longer maintained.
6.0.0 140 9/28/2026 6.0.0 is deprecated because it is no longer maintained.
5.9.0 140 9/27/2026 5.9.0 is deprecated because it is no longer maintained.
5.8.0 136 9/27/2026 5.8.0 is deprecated because it is no longer maintained.
5.7.0 130 9/26/2026 5.7.0 is deprecated because it is no longer maintained.
5.6.0 193 9/24/2026 5.6.0 is deprecated because it is no longer maintained.
5.5.1 261 9/11/2026 5.5.1 is deprecated because it is no longer maintained.
5.5.0 144 9/11/2026 5.5.0 is deprecated because it is no longer maintained.
5.4.0 187 9/2/2026 5.4.0 is deprecated because it is no longer maintained.
5.3.0 202 8/21/2026 5.3.0 is deprecated because it is no longer maintained.
Loading failed

https://github.com/yuebo119/PalORM/blob/main/CHANGELOG.md