如何在EF中实现Postgres内部类型xid8与.NET类型的映射转换？

问题背景 #

在.NET 7 + Npgsql.EntityFrameworkCore.PostgreSQL 7.0.1环境下，尝试将Postgres内部类型xid8映射到.NET的uint类型时，抛出转换异常：

Can't cast database type xid8 to Int64
   at Npgsql.Internal.TypeHandling.NpgsqlTypeHandler.ReadCustom[TAny](NpgsqlReadBuffer buf, Int32 len, Boolean async, FieldDescription fieldDescription) 
   at Npgsql.NpgsqlDataReader.GetFieldValue[T](Int32 ordinal)    
   at Npgsql.NpgsqlDataReader.GetInt64(Int32 ordinal)  

用户提供的核心代码：

实体类 #

public class History
{
    public Guid Id { get; }
    public uint VersionId { get; set; }
    public DateTimeOffset Date { get; set; }
    public string Status { get; set; }
}

DbContext配置 #

public class PostgresDbContext : DbContext
{
    public PostgresDbContext(DbContextOptions options)
        : base(options) { }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);

        modelBuilder.Entity<History>()
            .HasKey(x => x.Id);

        modelBuilder.Entity<History>()
            .Property(x => x.Date);

        modelBuilder.Entity<History>()
            .Property(x => x.Status);

        modelBuilder.Entity<History>()
            .Property(x => x.VersionId)
            .HasColumnName("txid");

        modelBuilder.Entity<History>()
            .ToTable("history");
    }
}

数据库表结构 #

CREATE TABLE IF NOT EXISTS public.history
(
    id uuid NOT NULL,
    date timestamp with time zone NOT NULL DEFAULT now(),
    status text COLLATE pg_catalog."default" NOT NULL,
    txid xid8 NOT NULL DEFAULT pg_current_xact_id(),
    CONSTRAINT history_pkey PRIMARY KEY (id)
)

解决方案 #

方案1：自定义Npgsql类型映射（推荐） #

Postgres的xid8是8字节无符号整数，最适配.NET的ulong类型，也可映射到string避免溢出风险。

1.1 注册类型映射

在DbContext的OnConfiguring方法中添加类型映射配置：

protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
    base.OnConfiguring(optionsBuilder);
    optionsBuilder.UseNpgsql("<你的连接字符串>", npgsqlOptions =>
    {
        // 注册xid8到ulong的映射
        npgsqlOptions.MapComposite<UlongXid8>("xid8");
        // 若需映射到string，替换为：
        // npgsqlOptions.MapComposite<StringXid8>("xid8");
    });
}

1.2 定义转换结构体

// 映射xid8到ulong的结构体
public struct UlongXid8
{
    public ulong Value { get; set; }

    public static explicit operator UlongXid8(ulong value) => new() { Value = value };
    public static explicit operator ulong(UlongXid8 xid) => xid.Value;
}

// 映射xid8到string的结构体（可选）
public struct StringXid8
{
    public string Value { get; set; }

    public static explicit operator StringXid8(string value) => new() { Value = value };
    public static explicit operator string(StringXid8 xid) => xid.Value;
}

1.3 更新实体与模型配置

修改实体类属性类型，并在模型配置中指定列类型：

public class History
{
    public Guid Id { get; }
    public UlongXid8 VersionId { get; set; } // 替换为自定义类型
    public DateTimeOffset Date { get; set; }
    public string Status { get; set; }
}

modelBuilder.Entity<History>()
    .Property(x => x.VersionId)
    .HasColumnName("txid")
    .HasColumnType("xid8"); // 明确指定数据库列类型

方案2：使用EF Core值转换器 #

若不想自定义复合类型，可直接通过值转换器实现字符串中转的类型转换：

modelBuilder.Entity<History>()
    .Property(x => x.VersionId)
    .HasColumnName("txid")
    .HasColumnType("xid8")
    .HasConversion(
        v => v.ToString(), // 写入时uint转string
        v => uint.Parse(v) // 读取时string转uint
    );

⚠️ 注意：若xid8的值超过uint的范围（0~4294967295），会触发溢出异常，此时建议改用ulong或string类型。

方案3：调整数据库列类型（可选） #

如果业务允许，可将txid列类型改为bigint或text，直接适配.NET的long或string类型，无需额外映射配置：

ALTER TABLE public.history ALTER COLUMN txid TYPE bigint;
-- 或改为text
ALTER TABLE public.history ALTER COLUMN txid TYPE text;

内容的提问来源于stack exchange，提问作者Jose Rodriguez