JCode.ORMX.DbProvider.PostgreSQL 1.0.3

JCode.ORMX.DbProvider.PostgreSQL

PostgreSQL 数据库提供程序，用于 JCode.ORMX 框架。该提供程序使您能够使用 PostgreSQL 作为 JCode.ORMX 的后端数据库。

功能特性

• 完整的 PostgreSQL 支持：支持 PostgreSQL 的所有基本操作
• 类型安全：使用强类型实体类，避免运行时错误
• LINQ 表达式树：使用 LINQ 表达式进行查询，编译时类型检查
• 表管理：自动创建和管理 PostgreSQL 表
• 事务支持：支持 PostgreSQL 事务操作
• 存储过程：支持 PostgreSQL 存储过程调用
• 批量操作：支持批量插入、更新、删除
• 参数化查询：自动参数化查询，防止 SQL 注入
• 连接池：内置连接池管理，提高性能
• JSON 支持：支持 PostgreSQL 的 JSON/JSONB 类型
• 数组类型：支持 PostgreSQL 的数组类型
• 全文搜索：支持 PostgreSQL 的全文搜索功能

安装

NuGet 包

Install-Package JCode.ORMX.DbProvider.PostgreSQL

依赖项

• Npgsql (6.x 或更高版本)
• JCode.ORMX (1.0.0 或更高版本)

快速开始

1. 定义实体类

[Table("Users")]
public class User
{
    [Column(IsPrimaryKey = true, IsIdentity = true)]
    public int Id { get; set; }

    [Column]
    public string Name { get; set; }

    [Column]
    public string Email { get; set; }

    [Column]
    public DateTime CreatedAt { get; set; }
}

2. 初始化 PostgreSQL 提供程序

// 使用连接字符串
var provider = new PostgreSQLProvider("Host=localhost;Database=MyDb;Username=postgres;Password=your_password;");

// 或使用连接字符串构建器
var builder = new NpgsqlConnectionStringBuilder
{
    Host = "localhost",
    Database = "MyDb",
    Username = "postgres",
    Password = "your_password",
    Port = 5432,
    SslMode = SslMode.Disable
};
var provider = new PostgreSQLProvider(builder.ToString());

3. 创建表

var tableManager = provider.GetTableManager();
tableManager.Create(typeof(User));

4. 基本操作

var table = tableManager.Table<User>();

// 插入
var user = new User 
{ 
    Name = "John", 
    Email = "john@example.com", 
    CreatedAt = DateTime.Now 
};
table.Insert(user);

// 查询
var users = table.Find()
    .Where(u => u.Name == "John")
    .OrderBy(u => u.Id)
    .Limit(10)
    .GetList();

// 更新
table.Update()
    .Set("Email", "newemail@example.com")
    .Where(u => u.Id == 1)
    .Execute();

// 删除
table.Delete()
    .Where(u => u.Id == 1)
    .Execute();

高级功能

事务操作

using (var transaction = provider.BeginTransaction())
{
    try
    {
        var table = transaction.Table<User>();
        
        table.Insert(user1);
        table.Insert(user2);
        
        transaction.Commit();
    }
    catch
    {
        transaction.Rollback();
        throw;
    }
}

JSON 类型支持

[Table("Products")]
public class Product
{
    [Column(IsPrimaryKey = true)]
    public int Id { get; set; }

    [Column]
    public string Name { get; set; }

    [Column]
    public Dictionary<string, object> Attributes { get; set; }  // JSONB 类型
}

// 查询 JSON 字段
var products = table.Find()
    .Where(p => p.Attributes["color"] == "red")
    .GetList();

数组类型支持

[Table("Articles")]
public class Article
{
    [Column(IsPrimaryKey = true)]
    public int Id { get; set; }

    [Column]
    public string Title { get; set; }

    [Column]
    public string[] Tags { get; set; }  // 数组类型
}

// 查询数组字段
var articles = table.Find()
    .Where(a => a.Tags.Contains("technology"))
    .GetList();

全文搜索

// 创建全文搜索索引
table.CreateIndex("Title", "gin");

// 使用全文搜索
var results = table.Find()
    .Where(a => a.Title.ToTsVector() @@ "search query".ToTsQuery())
    .GetList();

聚合查询

var result = table.Aggregate()
    .GroupBy("Department")
    .Count("EmployeeCount", "Id")
    .Avg("AvgSalary", "Salary")
    .Sum("TotalSalary", "Salary")
    .GetList();

连接查询

var result = table.Find()
    .InnerJoin<Order>((u, o) => u.Id == o.UserId)
    .Where(u => u.Name == "John")
    .GetList();

批量操作

// 批量插入
var users = new List<User> { /* ... */ };
table.InsertAll(users);

// 批量更新
table.UpdateAll(users);

// 批量删除
table.DeleteAll(users);

配置选项

连接字符串选项

var connectionString = "Host=localhost;Database=MyDb;Username=postgres;Password=your_password;" +
    "Port=5432;" +
    "SslMode=Disable;" +
    "Timeout=30;" +
    "CommandTimeout=30;" +
    "Pooling=true;" +
    "MinPoolSize=5;" +
    "MaxPoolSize=100;" +
    "ConnectionIdleLifetime=300";

var provider = new PostgreSQLProvider(connectionString);

高级配置

var builder = new NpgsqlConnectionStringBuilder
{
    Host = "localhost",
    Database = "MyDb",
    Username = "postgres",
    Password = "your_password",
    Port = 5432,
    SslMode = SslMode.Disable,
    Timeout = 30,
    CommandTimeout = 30,
    Pooling = true,
    MinPoolSize = 5,
    MaxPoolSize = 100,
    ConnectionIdleLifetime = 300,
    Keepalive = 60,
    TCPKeepAlive = true
};

var provider = new PostgreSQLProvider(builder.ToString());

类型映射

PostgreSQL 提供程序支持以下 .NET 类型到 PostgreSQL 类型的映射：

性能建议

1. 使用索引：为常用查询字段创建索引，特别是 JSON 字段使用 GIN 索引
2. 批量操作：使用 InsertAll、UpdateAll、DeleteAll 进行批量操作
3. 查询优化：只查询需要的字段，使用 LIMIT 限制结果集
4. 连接池：合理配置连接池大小
5. 事务范围：尽量缩小事务范围，减少锁持有时间
6. 避免 N+1 查询：使用连接查询代替多次查询
7. 使用 EXPLAIN：分析查询计划，优化慢查询
8. 分区表：对大表考虑使用分区

故障排除

常见问题

Q: 连接超时 A: 增加 Timeout 和 CommandTimeout 参数的值

Q: SSL 连接错误 A: 设置 SslMode=Disable 或配置正确的 SSL 证书

Q: JSON 查询失败 A: 确保使用了正确的 JSON 操作符（如 ->、->>、@>）

Q: 数组查询失败 A: 使用 ANY、ALL 或 CONTAINS 操作符

Q: 查询性能慢 A: 使用 EXPLAIN ANALYZE 分析查询计划，添加适当的索引

Q: 批量操作失败 A: 检查 work_mem 配置，增加其值以支持大批量操作