LinqToDB 中 PostgreSQL 枚举数组类型的处理实践

背景介绍

在 PostgreSQL 数据库中，枚举类型(ENUM)和枚举数组类型(ENUM[])是两种非常有用的数据类型，它们可以确保数据的一致性和完整性。然而，在使用 LinqToDB 这样的 ORM 框架时，处理这些特殊类型可能会遇到一些挑战。

问题现象

在使用 LinqToDB 5.4.1 版本与 PostgreSQL 16 数据库交互时，开发者发现对于枚举类型的单值列(ENUM)可以正常进行 CRUD 操作，但对于枚举数组类型(ENUM[])却遇到了插入和更新的问题。

技术分析

1. 基础模型定义

首先，开发者定义了 PostgreSQL 中的枚举类型和对应的表结构：

CREATE TYPE "item_type_enum" AS ENUM (
  'type1',
  'type2',
  'type3'
);

CREATE TABLE IF NOT EXISTS "item" (
  "id" INT NOT NULL,
  "type" "item_type_enum",
  "types" "item_type_enum"[],
  CONSTRAINT pk_item PRIMARY KEY (id)
);

对应的 C# 模型定义如下：

[PgName("item_type_enum")]
public enum ItemTypeEnum {
    [PgName("type1")] [MapValue("type1")] Type1,
    [PgName("type2")] [MapValue("type2")] Type2,
    [PgName("type3")] [MapValue("type3")] Type3,
}

[Table(Schema = "public", Name = "item")]
public partial class Item {
    [Column("id", DataType = DataType.Int32), PrimaryKey, NotNull] 
    public int Id { get; set; }
    
    [Column("type", DataType = DataType.Enum), Nullable] 
    public ItemTypeEnum? Type { get; set; }
    
    [Column("types", DataType = DataType.Enum), Nullable] 
    public ItemTypeEnum[] Types { get; set; }
}

2. 问题表现

当尝试插入枚举数组数据时：

await table
    .Value(x => x.Id, 3)
    .Value(x => x.Types, [ItemTypeEnum.Type1, ItemTypeEnum.Type2])
    .InsertAsync();

会遇到两种不同的错误：

1. 未配置映射时：报错提示 CLR 类型 System.Object 不被 Npgsql 原生支持
2. 配置简单映射后：报错提示类型不匹配，无法将 text 类型转换为 item_type_enum[]

解决方案

1. 正确的映射配置

要解决这个问题，需要为枚举数组类型配置正确的映射转换器。以下是完整的解决方案：

static DataOptions GetOptions(string connectionString) {
    var builder = new NpgsqlDataSourceBuilder(connectionString);
    builder.MapEnum<ItemTypeEnum>("item_type_enum"); // 明确指定枚举类型名称
    
    var mapping = new MappingSchema();
    
    // 配置枚举数组类型的转换器
    mapping.SetConverter<ItemTypeEnum[], DataParameter>(arr => {
        var values = arr.Select(e => e.ToString().ToLower()).ToArray();
        return new DataParameter {
            DataType = DataType.Enum,
            DbType = "item_type_enum[]",
            Value = values
        };
    });
    
    var dataProvider = PostgreSQLTools.GetDataProvider(PostgreSQLVersion.v95);
    var dataSource = builder.Build();
    
    return new DataOptions()
        .UseConnectionFactory(dataProvider, _ => dataSource.CreateConnection())
        .UseMappingSchema(mapping);
}

2. 关键点说明

1. Npgsql 枚举映射：必须通过 MapEnum 方法明确注册枚举类型，并指定 PostgreSQL 中的类型名称
2. 数组转换器：需要为枚举数组类型配置专门的转换器，将 C# 数组转换为 PostgreSQL 能识别的格式
3. 数据类型指定：在转换器中明确指定 DataType 为 Enum 和 DbType 为 item_type_enum[]

深入理解

1. PostgreSQL 枚举数组的存储格式

PostgreSQL 中的数组类型有其特定的文本表示格式：

• 一维数组使用花括号包裹，元素间用逗号分隔：{value1,value2}
• 多维数组使用嵌套的花括号表示

2. LinqToDB 的类型处理机制

LinqToDB 通过以下步骤处理参数：

1. 检查是否有为该类型定义的自定义转换器
2. 如果没有，尝试使用默认的类型处理逻辑
3. 对于复杂类型，需要明确指定如何转换为 SQL 参数

3. Npgsql 的类型映射

Npgsql 作为 ADO.NET 提供程序，需要知道如何：

• 将 .NET 类型映射到 PostgreSQL 类型
• 如何序列化和反序列化这些类型的值

最佳实践

1. 明确指定类型名称：在映射时总是明确指定 PostgreSQL 中的类型名称
2. 完整的映射配置：为枚举类型和枚举数组类型都配置映射
3. 测试验证：在配置后执行简单的 CRUD 操作验证映射是否正确
4. 日志记录：开启 LinqToDB 的日志记录，方便调试 SQL 生成和参数传递

总结

处理 PostgreSQL 枚举数组类型在 LinqToDB 中需要一些额外的配置工作，主要是需要正确设置类型映射和转换器。通过理解 PostgreSQL 数组的存储格式和 LinqToDB 的类型处理机制，我们可以构建出稳定可靠的解决方案。这种模式不仅适用于枚举数组，也可以推广到其他 PostgreSQL 自定义类型的数组处理场景中。