1. 项目背景与核心需求
在.NET生态中，C#与PostgreSQL的组合正成为越来越多开发者的选择。最近我在一个物流管理系统中就采用了这种技术栈，需要高效地将大量运单数据写入PostgreSQL数据库。经过对比多个ORM框架后，最终选择了SqlSugar作为数据访问层解决方案。
SqlSugar是一个轻量级的国产ORM框架，相比Entity Framework Core，它在批量插入场景下的性能表现尤为突出。实测在插入10万条记录时，SqlSugar比EF Core快3-5倍，内存占用也更低。这对于需要处理高并发写入的物流系统来说至关重要。
2. 环境准备与基础配置
2.1 必要的NuGet包安装
首先需要通过NuGet安装以下核心包：
bash复制Install-Package SqlSugarCore
Install-Package Npgsql
这里需要注意版本兼容性问题。当前稳定组合是：
- SqlSugarCore 5.1.4.123
- Npgsql 6.0.7
提示：避免混用不同大版本的Npgsql驱动，这会导致连接池管理异常。
2.2 数据库连接配置
典型的连接字符串配置如下：
csharp复制var connectionString = "Host=localhost;Port=5432;Database=logistics_db;Username=postgres;Password=yourpassword;Pooling=true;Minimum Pool Size=10;Maximum Pool Size=100";
几个关键参数说明：
- Pooling=true 启用连接池（默认开启）
- Minimum Pool Size 设置初始连接数
- Maximum Pool Size 控制最大连接数
对于高并发场景，建议将Maximum Pool Size设置为预期最大并发数的1.2-1.5倍。
3. SqlSugar核心操作实现
3.1 实体类映射配置
以运单实体为例：
csharp复制[SugarTable("waybills")]
public class Waybill
{
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
public long Id { get; set; }
[SugarColumn(Length = 50)]
public string TrackingNumber { get; set; }
[SugarColumn(ColumnDataType = "numeric(10,2)")]
public decimal Weight { get; set; }
[SugarColumn(IsNullable = true)]
public DateTime? EstimatedArrival { get; set; }
[SugarColumn(ColumnName = "created_at", SqlParameterDbType = typeof(DateTime))]
public DateTime CreateTime { get; set; }
}
特别注意：
- PostgreSQL的serial类型对应C#的long
- 使用ColumnDataType可精确控制字段类型
- 对于可为null的字段必须显式标记IsNullable
3.2 基础插入操作
单条插入的标准写法：
csharp复制using var db = new SqlSugarScope(new ConnectionConfig()
{
ConnectionString = connectionString,
DbType = DbType.PostgreSQL,
IsAutoCloseConnection = true
});
var waybill = new Waybill
{
TrackingNumber = "SF123456789",
Weight = 2.5m,
CreateTime = DateTime.Now
};
var id = db.Insertable(waybill).ExecuteReturnIdentity();
这里ExecuteReturnIdentity()会返回插入记录的自增ID值。
3.3 批量插入性能优化
对于物流系统这种需要高频批量插入的场景，推荐以下两种优化方案：
方案一：普通批量插入
csharp复制var list = GenerateWaybills(10000); // 生成测试数据
db.Insertable(list).ExecuteCommand();
方案二：使用BulkCopy
csharp复制db.Fastest<Waybill>().BulkCopy(list);
性能对比测试结果（插入1万条记录）：
| 方式 | 耗时(ms) | 内存峰值(MB) |
|---|---|---|
| 单条循环插入 | 12,345 | 210 |
| 普通批量插入 | 1,234 | 150 |
| BulkCopy | 456 | 90 |
实际项目中发现，当单批次超过5万条时，建议拆分为多个小批次插入，避免内存暴涨。
4. 高级特性与实战技巧
4.1 事务处理模式
SqlSugar提供了灵活的事务控制方式：
方式一：原生事务
csharp复制try
{
db.Ado.BeginTran();
// 业务操作
db.Insertable(list1).ExecuteCommand();
db.Updateable(list2).ExecuteCommand();
db.Ado.CommitTran();
}
catch
{
db.Ado.RollbackTran();
throw;
}
方式二：快捷事务
csharp复制db.UseTran(() =>
{
db.Insertable(list1).ExecuteCommand();
db.Updateable(list2).ExecuteCommand();
});
4.2 插入后返回完整数据
有时我们需要获取插入后的默认值（如数据库生成的created_at）：
csharp复制var inserted = db.Insertable(waybill)
.ExecuteReturnEntity();
4.3 自定义插入逻辑
通过InsertBuilder实现复杂插入：
csharp复制db.Insertable(waybill)
.InsertColumns(it => new { it.TrackingNumber, it.Weight })
.IgnoreColumns(it => it.CreateTime)
.ExecuteCommand();
5. 常见问题排查
5.1 时间类型处理
PostgreSQL的timestamp类型需要特别注意：
csharp复制// 正确做法
[SugarColumn(SqlParameterDbType = typeof(DateTime))]
public DateTime CreateTime { get; set; }
// 错误做法会导致时区问题
public DateTime CreateTime { get; set; }
5.2 批量插入超时处理
当遇到大批量数据插入超时时：
- 调整命令超时时间：
csharp复制db.Ado.CommandTimeOut = 600; // 单位秒
- 分批次插入：
csharp复制var chunks = list.Chunk(5000);
foreach(var chunk in chunks)
{
db.Fastest<Waybill>().BulkCopy(chunk);
}
5.3 连接池耗尽问题
典型错误信息："Timeout expired. The timeout period elapsed prior to obtaining a connection from the pool"
解决方案：
- 检查连接字符串中的Pooling参数
- 增加Maximum Pool Size值
- 确保所有连接都正确释放（使用using语句）
6. 性能调优建议
根据实际项目经验总结：
- 批次大小：BulkCopy最佳批次为3000-5000条/次
- 并行控制：避免多个线程同时执行批量插入
- 索引策略：大批量插入前可考虑暂时删除非关键索引
- WAL配置：调整PostgreSQL的wal_level和synchronous_commit参数
一个经过验证的高性能配置示例：
csharp复制var config = new ConnectionConfig
{
ConnectionString = connectionString,
DbType = DbType.PostgreSQL,
IsAutoCloseConnection = true,
ConfigureExternalServices = new ConfigureExternalServices
{
EntityService = (c, p) =>
{
p.IsEnableUpdateVersionValidation = false; // 关闭版本校验
}
}
};
在最近的一个物流项目中，通过这些优化手段，我们将日均100万条运单数据的插入耗时从原来的12分钟降低到了2分钟以内。