Sqlx 0.6.0

Sqlx

编译时源生成器，构建类型安全、高性能的 .NET 数据库访问层。零运行时反射，完全 AOT 兼容。

核心特性

• 编译时生成 - 零反射，接近原生 ADO.NET 性能
• 类型安全 - 编译时捕获 SQL 错误
• 多数据库 - SQLite、PostgreSQL、MySQL、SQL Server、Oracle、DB2
• 智能模板 - 占位符自动适配不同数据库方言
• AOT 兼容 - 完全支持 Native AOT

快速开始

dotnet add package Sqlx

// 1. 定义实体
[SqlxEntity, SqlxParameter, TableName("users")]
public class User
{
    [Key] public long Id { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
}

// 2. 定义仓储接口
public interface IUserRepository : ICrudRepository<User, long>
{
    [SqlTemplate("SELECT {{columns}} FROM {{table}} WHERE age >= @minAge")]
    Task<List<User>> GetAdultsAsync(int minAge);
}

// 3. 实现仓储（代码自动生成）
[SqlDefine(SqlDefineTypes.SQLite)]
[RepositoryFor(typeof(IUserRepository))]
public partial class UserRepository(DbConnection connection) : IUserRepository { }

// 4. 使用
await using var conn = new SqliteConnection("Data Source=app.db");
var repo = new UserRepository(conn);
var adults = await repo.GetAdultsAsync(18);

SQL 模板占位符

占位符自动适配不同数据库方言：

各数据库生成的 SQL：

内置仓储接口

继承 ICrudRepository<TEntity, TKey> 获得标准 CRUD 方法：

public interface IUserRepository : ICrudRepository<User, long>
{
    // 继承方法: GetByIdAsync, GetAllAsync, InsertAndGetIdAsync, 
    // UpdateAsync, DeleteAsync, CountAsync, ExistsAsync...
    
    // 自定义方法
    [SqlTemplate("SELECT {{columns}} FROM {{table}} WHERE name LIKE @pattern")]
    Task<List<User>> SearchByNameAsync(string pattern);
}

条件占位符

// 动态搜索：只在参数有值时添加条件
[SqlTemplate(@"
    SELECT {{columns}} FROM {{table}} WHERE 1=1 
    {{if notnull=name}}AND name LIKE @name{{/if}}
    {{if notnull=minAge}}AND age >= @minAge{{/if}}
")]
Task<List<User>> SearchAsync(string? name, int? minAge);

IQueryable 查询构建器

使用标准 LINQ 语法构建类型安全的 SQL 查询：

using Sqlx;

// 基本查询
var sql = SqlQuery.ForSqlite<User>()
    .Where(u => u.Age >= 18 && u.IsActive)
    .OrderBy(u => u.Name)
    .Take(10)
    .ToSql();
// SELECT * FROM [User] WHERE ([age] >= 18 AND [is_active] = 1) ORDER BY [name] ASC LIMIT 10

// 投影查询
var sql = SqlQuery.ForPostgreSQL<User>()
    .Where(u => u.Name.Contains("test"))
    .Select(u => new { u.Id, u.Name })
    .ToSql();
// SELECT "id", "name" FROM "User" WHERE "name" LIKE '%' || 'test' || '%'

// 参数化查询
var (sql, parameters) = SqlQuery.ForSqlServer<User>()
    .Where(u => u.Age > 18)
    .ToSqlWithParameters();
// SQL: SELECT * FROM [User] WHERE [age] > @p0
// Parameters: { "@p0": 18 }

支持的 LINQ 方法：

• Where - 条件过滤（支持 String/Math 方法、null 合并、条件表达式）
• Select - 投影（支持匿名类型、函数调用）
• OrderBy / OrderByDescending / ThenBy / ThenByDescending - 排序
• Take / Skip - 分页
• GroupBy - 分组
• Distinct - 去重

支持的函数：

• String: Contains, StartsWith, EndsWith, ToUpper, ToLower, Trim, Substring, Replace, Length
• Math: Abs, Round, Floor, Ceiling, Sqrt, Pow, Min, Max

表达式查询（仓储模式）

// 在仓储中使用 LINQ 表达式
[SqlTemplate("SELECT {{columns}} FROM {{table}} WHERE {{where --param predicate}}")]
Task<List<User>> GetWhereAsync(Expression<Func<User, bool>> predicate);

// 使用
var adults = await repo.GetWhereAsync(u => u.Age >= 18 && u.IsActive);

批量执行

var users = new List<User> { new() { Name = "Alice" }, new() { Name = "Bob" } };
var sql = "INSERT INTO users (name) VALUES (@name)";
await connection.ExecuteBatchAsync(sql, users, UserParameterBinder.Default);

性能对比

基于 BenchmarkDotNet 测试（SQLite 内存数据库，10000 条记录）：

.NET 10 性能（最新 LTS）

测试环境： .NET 10.0.2 (LTS), BenchmarkDotNet 0.15.7, AMD Ryzen 7 5800H

详细数据见 性能基准测试

支持的数据库

推荐： .NET 10 (LTS) - 支持到 2028 年 11 月

更多文档

• 快速开始
• SQL 模板
• 数据库方言
• 源生成器
• 性能基准测试
• API 参考
• AI 助手指南
• 示例项目

许可证

MIT License - 详见 LICENSE.txt