本文将详细讲解在asp.net core webapi项目中，基于SqlSugarCore ORM框架实现PostgreSQL数据库的连接、配置、CRUD操作，适配.NET 6/.NET 7/.NET 8主流版本，全程无冗余配置，可直接落地项目。
一、环境准备
1.1 开发环境
- 开发工具：Rider
- 运行环境：.NET 6+ （推荐.NET 8 LTS）
- 数据库：PostgreSQL 12+ （本地/服务器部署均可）
- ORM框架：SqlSugarCore 5.1.4.214（固定稳定版本）
1.2 数据库准备
提前安装PostgreSQL数据库，创建空数据库（示例数据库名：SqlSugarPgDb），无需手动创建数据表，后续通过SqlSugarCore代码自动建表。同时记录数据库连接所需参数：地址、端口、数据库名、账号、密码。
二、创建asp.net core webapi项目
- 打开Rider开发工具，点击首页New Solution新建解决方案项目
- 在项目模板中选择asp.net core webapi，自定义项目名称、存储路径，选择对应的.NET框架（如.NET 8）
- 取消Configure for HTTPS（HTTPS配置），点击创建，生成纯净的asp.net core webapi空项目
三、安装必要NuGet包
通过Rider内置NuGet包管理器或NuGet控制台，安装以下两个核心包（适配PostgreSQL专属依赖）：
- SqlSugarCore：.NET Core 专属核心ORM框架，提供数据库操作能力
- Npgsql：PostgreSQL官方ADO.NET驱动，SqlSugarCore操作PG数据库必须依赖
本次项目固定使用SqlSugarCore 5.1.4.214 版本，提供两种Rider安装方式（图形化安装+终端命令安装），可任选其一：
方式一：Rider可视化NuGet包管理器安装（推荐）
1. 在Rider右侧面板找到【NuGet】包管理工具，打开包搜索界面；
2. 在搜索框输入 SqlSugarCore，检索对应组件；
3. 在版本下拉列表中，精准选择 5.1.4.214 固定版本；
4. 点击安装，等待Rider自动完成组件引入与引用配置。
方式二：.NET CLI 终端命令安装
打开Rider底部Terminal终端，切换到项目根目录，执行标准 .NET CLI 命令精准安装指定版本：
dotnet add package SqlSugarCore --version 5.1.4.214
四、配置数据库连接字符串
在项目根目录的appsettings.json中添加PostgreSQL数据库连接配置，替换为自己的数据库参数：
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"ConnectionStrings": {
"PgSqlConnection": "Host=localhost;Port=5432;Database=SqlSugarPgDb;Username=postgres;Password=123456;Pooling=true;Maximum Pool Size=100"
},
"AllowedHosts": "*"
}
参数说明：Host为数据库地址、Port默认5432、Database为目标库名、Username为数据库账号、Password为登录密码；Pooling开启连接池、Maximum Pool Size设置最大连接数，提升高并发下的性能。
五、注册SqlSugarCore全局服务
在Program.cs中配置SqlSugar参数，注册为全局单例服务，适配PostgreSQL数据库，开启日志、自动建表等功能：
using SqlSugar;
using SqlSugarPgDemo.Extensions;
var builder = WebApplication.CreateBuilder(args);
// 注册控制器
builder.Services.AddControllers();
// 注册Swagger文档
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
// 注册SqlSugarCore服务
builder.Services.AddScoped<ISqlSugarClient>(sp =>
{
var db = new SqlSugarClient(new ConnectionConfig()
{
// 数据库类型指定为PostgreSQL
DbType = DbType.PostgreSQL,
ConnectionString = builder.Configuration.GetConnectionString("PgSqlConnection"),
// 开启自动释放数据库连接
IsAutoCloseConnection = true,
MoreSettings = new ConnMoreSettings()
{
PgSqlIsAutoToLower = false, // 是否自动转小写
*PgSqlIsAutoToLowerCodeFirst = false, // CodeFirst时是否转小写
}
});
// 开启SQL日志输出（控制台打印执行的SQL语句，方便调试）
db.Aop.OnLogExecuting = (sql, pars) =>
{
Console.WriteLine($"执行SQL：{sql}\r\n参数：{string.Join(",", pars.Select(p => p.Value))}");
};
return db;
});
var app = builder.Build();
// 启用Swagger
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
app.UseAuthorization();
app.MapControllers();
// 初始化数据库表
app.InitTables();
app.Run();
六、创建实体类（数据库表映射）
新建Entity文件夹，创建测试实体类 User.cs，SqlSugarCore可通过该实体自动生成数据库表：
using SqlSugar;
namespace SqlSugarPgDemo.Entity
{
/// <summary>
/// 用户实体（自动映射user表）
/// </summary>
[SugarTable("sys_user")] // 指定数据库表名
public class User
{
/// <summary>
/// 主键ID（自增）
/// </summary>
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)] // 主键、自增
public int Id {
get; set; }
/// <summary>
/// 用户名
/// </summary>
[SugarColumn(Length = 50, IsNullable = false)] // 字段长度、非空
public string UserName {
get; set; } = string.Empty;
/// <summary>
/// 手机号
/// </summary>
[SugarColumn(Length = 11, IsNullable = true)]
public string? Phone {
get; set; }
/// <summary>
/// 创建时间
/// </summary>
[SugarColumn(IsNullable = true)]
public DateTime? CreateTime {
get; set; }
}
}
核心特性说明：SugarTable指定表名，SugarColumn配置字段属性（主键、自增、长度、是否为空），完美适配PostgreSQL字段规则。
七、项目启动自动初始化数据库表（扩展类方式）
本文采用项目启动自动建表方案，无需手动调用接口，通过自定义扩展类实现程序启动时自动根据实体类创建数据表，不存在则创建，已存在则忽略，适配PostgreSQL数据库。首先在项目中新建 Extensions 文件夹，创建扩展静态类 Extensions.cs：
using SqlSugar;
using SqlSugarPgDemo.Entity;
using Microsoft.AspNetCore.Builder;
namespace SqlSugarPgDemo.Extensions;
public static class Extensions
{
/// <summary>
/// 项目启动初始化数据库表
/// </summary>
/// <param name="app"></param>
public static void InitTables(this IApplicationBuilder app)
{
// 创建服务作用域，获取SqlSugarCore实例
using var scope = app.ApplicationServices.CreateScope();
var db = scope.ServiceProvider.GetRequiredService<ISqlSugarClient>();
// 自动根据实体初始化数据表
db.CodeFirst.InitTables<User>();
}
}
扩展类编写完成后，已在前文Program.cs中引入调用 app.InitTables();，无需手动调用接口。在Rider中点击右上角运行按钮启动项目，程序启动完成后，会自动在PostgreSQL数据库中生成 sys_user 数据表，全程无需人工干预。
八、实现CRUD核心接口
新建 UserController.cs，实现新增、查询、修改、删除、分页查询等常用数据库操作：
using Microsoft.AspNetCore.Mvc;
using SqlSugar;
using SqlSugarPgDemo.Entity;
namespace SqlSugarPgDemo.Controllers;
[Route("api/**[controller]**")]
[ApiController]
public class UserController : ControllerBase
{
private readonly ISqlSugarClient _db;
public UserController(ISqlSugarClient db)
{
_db = db;
}
/// <summary>
/// 新增用户
/// </summary>
[HttpPost("Add")]
public async Task<IActionResult> AddUser([FromBody] User user)
{
user.CreateTime = DateTime.Now;
int id = await _db.Insertable(user).ExecuteReturnIdentityAsync();
return Ok($"新增成功，用户ID：{id}");
}
/// <summary>
/// 根据ID查询用户
/// </summary>
[HttpGet("GetById/{id}")]
public async Task<IActionResult> GetUserById(int id)
{
var user = await _db.Queryable<User>().InSingleAsync(id);
return Ok(user);
}
/// <summary>
/// 查询所有用户
/// </summary>
[HttpGet("GetAll")]
public async Task<IActionResult> GetAllUser()
{
var list = await _db.Queryable<User>().ToListAsync();
return Ok(list);
}
/// <summary>
/// 分页查询用户
/// </summary>
[HttpGet("GetPage")]
public async Task<IActionResult> GetPageUser(int pageIndex = 1, int pageSize = 10)
{
var pageData = await _db.Queryable<User>()
.ToPageListAsync(pageIndex, pageSize);
return Ok(pageData);
}
/// <summary>
/// 修改用户信息
/// </summary>
[HttpPut("Update")]
public async Task<IActionResult> UpdateUser([FromBody] User user)
{
int rows = await _db.Updateable(user).UpdateColumns(x => new { x.UserName, x.Phone }).ExecuteCommandAsync();
return Ok($"修改成功，影响行数：{rows}");
}
/// <summary>
/// 删除用户
/// </summary>
[HttpDelete("Delete/{id}")]
public async Task<IActionResult> DeleteUser(int id)
{
int rows = await _db.Deleteable<User>().In(id).ExecuteCommandAsync();
return Ok($"删除成功，影响行数：{rows}");
}
}
九、常见问题排查
- 数据库连接失败：检查PostgreSQL服务是否正常运行、默认端口5432是否未被占用、连接字符串的地址、库名、账号密码是否正确，确保本地数据库已提前创建。
- 主键自增失效：实体主键必须配置
IsIdentity = true，PostgreSQL依赖序列实现自增，CodeFirst建表会自动生成序列，请勿手动修改数据表主键规则。 - SQL语法兼容报错：注册服务时必须指定
DbType.PostgreSQL，严格适配PG数据库语法，禁止使用SqlServer默认配置，否则会出现语法解析异常。 - 表名字段大小写适配问题：本项目已关闭PG自动转小写配置（
PgSqlIsAutoToLower=false），实体特性配置的表名、字段名需和数据库严格一致，统一采用小写命名规范即可正常适配。 - 项目启动建表无效：检查Program.cs中是否正确调用
app.InitTables()扩展方法，确保SqlSugarCore服务注册正常、服务作用域可正常获取数据库实例。
十、总结
通过以上完整步骤，已从零完成 asp.net core webapi + SqlSugarCore 5.1.4.214 + PostgreSQL 的基础整合配置。教程全程基于Rider开发环境，采用.NET CLI标准安装方式、规范的数据库连接配置、程序启动自动CodeFirst建表方案，同时实现了全套异步CRUD基础接口（新增、查询、修改、删除、分页查询）。SqlSugarCore完美适配PostgreSQL数据库特性，规避了大小写兼容、语法适配等常见坑，配置简洁、代码轻量化，满足项目基础数据库开发需求，可直接用于日常开发与项目落地。
十一、项目源码地址
本文完整实战项目代码已上传至码云Gitee，包含所有配置文件、实体类、扩展方法、CRUD接口，可直接克隆运行学习：
Gitee仓库地址：https://gitcode.com/GUOGUOXYES/SqlSugarPgDemo
仓库代码与本文教程完全同步，基于 Rider + asp.net core webapi + SqlSugarCore 5.1.4.214 + PostgreSQL 实现，开箱即用。
