NinoFloris · Apr 22, 2026 · Apr 20, 2026 · Apr 22, 2026 · May 19, 2026 · May 23, 2026
@@ -4,6 +4,7 @@
 using System.Collections.Concurrent;
 using System.Diagnostics;
 using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
 using System.Threading;
 using System.Threading.Tasks;
 using Npgsql.Internal.Postgres;
@@ -75,53 +76,44 @@ sealed class ArrayBased<TElement>(PgConcreteTypeInfo elementTypeInfo, Type? effe
     {
         readonly PgConverter<TElement> _elemConverter = (PgConverter<TElement>)elementTypeInfo.GetConverter(DataFormat.Binary);
 
+        // When the effective array type's element type differs from TElement (e.g. IntEnum[] with TElement=int,
+        // or IntEnum?[] with TElement=int?), CreateCollection uses Array.CreateInstanceFromArrayType to produce
+        // the correctly-typed array. Per-element access is a ref-byte-cast over the actual array's data
+        // reference at the row-major flat index — sound for layout-equivalent blittable value-type element
+        // pairs (the resolver gates this at call site), since sizeof(TElement?) matches the actual slot
+        // stride. The cast is on the element slot, not the array instance, so we don't assume the array's
+        // MethodTable matches TElement?[]; that's the part `Unsafe.As<TElement?[]>(actualArray)` would have
+        // gotten wrong for the Nullable<>[] case (no CLR variance through Nullable).
+        readonly Type? _effectiveType =
+            effectiveType is { IsArray: true } && effectiveType.GetElementType() != typeof(TElement) ? effectiveType : null;
+
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        static TElement? GetValue(object collection, IterationIndices indices)
+        static ref TElement? GetSlot(object collection, IterationIndices indices)
         {
             Debug.Assert(indices.Rank > 0);
-            switch (indices.Rank)
-            {
-            case 1:
-                // Justification: exact type Unsafe.As used to avoid the cast overhead for per element calls.
-                Debug.Assert(collection is TElement?[]);
-                return Unsafe.As<TElement?[]>(collection)[indices.One];
-            case 2:
-                // Justification: exact type Unsafe.As used to avoid the cast overhead for per element calls.
-                Debug.Assert(collection is TElement?[,]);
-                return Unsafe.As<TElement?[,]>(collection)[indices.Many![0], indices.Many![1]];
-            default:
-                // Justification: exact type Unsafe.As used to avoid the cast overhead for per element calls.
-                Debug.Assert(collection is Array);
-                return (TElement?)Unsafe.As<Array>(collection).GetValue(indices.Many!);
-            }
+            Debug.Assert(collection is Array);
+            ref var first = ref Unsafe.As<byte, TElement?>(ref MemoryMarshal.GetArrayDataReference(Unsafe.As<Array>(collection)));
+            return ref Unsafe.Add(ref first, (nint)indices.IndicesSum);
         }
 
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        static TElement? GetValue(object collection, IterationIndices indices) => GetSlot(collection, indices);
+
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         static void SetValue(object collection, IterationIndices indices, TElement? value)
-        {
-            Debug.Assert(indices.Rank > 0);
-            switch (indices.Rank)
-            {
-                case 1:
-                    // Justification: exact type Unsafe.As used to avoid the cast overhead for per element calls.
-                    Debug.Assert(collection is TElement?[]);
-                    Unsafe.As<TElement?[]>(collection)[indices.One] = value;
-                    break;
-                case 2:
-                    // Justification: exact type Unsafe.As used to avoid the cast overhead for per element calls.
-                    Debug.Assert(collection is TElement?[,]);
-                    Unsafe.As<TElement?[,]>(collection)[indices.Many![0], indices.Many![1]] = value;
-                    break;
-                default:
-                    // Justification: exact type Unsafe.As used to avoid the cast overhead for per element calls.
-                    Debug.Assert(collection is Array);
-                    Unsafe.As<Array>(collection).SetValue(value, indices.Many!);
-                    break;
-            }
-        }
+            => GetSlot(collection, indices) = value;
 
         object IElementOperations.CreateCollection(ReadOnlySpan<int> lengths)
-            => lengths.Length switch
+        {
+            if (_effectiveType is { } arrayType)
+                return lengths.Length switch
+                {
+                    0 => Array.CreateInstanceFromArrayType(arrayType, 0),
+                    1 => Array.CreateInstanceFromArrayType(arrayType, lengths[0]),
+                    _ => Array.CreateInstanceFromArrayType(arrayType, lengths.ToArray())
+                };
+
+            return lengths.Length switch
             {
                 0 => Array.Empty<TElement?>(),
                 1 => new TElement?[lengths[0]],
@@ -130,10 +122,9 @@ object IElementOperations.CreateCollection(ReadOnlySpan<int> lengths)
                 4 => new TElement?[lengths[0], lengths[1], lengths[2], lengths[3]],
                 5 => new TElement?[lengths[0], lengths[1], lengths[2], lengths[3], lengths[4]],
                 6 => new TElement?[lengths[0], lengths[1], lengths[2], lengths[3], lengths[4], lengths[5]],
-                7 => new TElement?[lengths[0], lengths[1], lengths[2], lengths[3], lengths[4], lengths[5], lengths[6]],
-                8 => new TElement?[lengths[0], lengths[1], lengths[2], lengths[3], lengths[4], lengths[5], lengths[6], lengths[7]],
-                _ => throw new InvalidOperationException("Postgres arrays can have at most 8 dimensions.")
+                _ => throw new InvalidOperationException("Postgres arrays can have at most 6 dimensions.")
             };
+        }
 
         int IElementOperations.GetCollectionCount(object collection, out int[]? lengths)
             => ArrayConverterCore.GetArrayLengths((Array)collection, out lengths);

@@ -411,7 +411,7 @@ public void RentElementBuffer(int totalElements)
 
 readonly struct PgArrayMetadata
 {
-    const int MaxDimensions = 8;
+    const int MaxDimensions = 6;
 
     readonly int _totalElements;
     readonly int[]? _dimensionLengths;

@@ -0,0 +1,152 @@
+using System;
+using System.Numerics;
+using System.Runtime.CompilerServices;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Npgsql.Internal.Converters;
+
+/// <summary>
+/// Non-generic marker for <see cref="EnumUnderlyingConverter{T}"/>. Used by <see cref="PgConcreteTypeInfo"/> at
+/// construction time to enforce that only this converter may participate in enum reported-type widening.
+/// </summary>
+interface IEnumUnderlyingConverter
+{
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    static bool IsEnumUnderlyingConversion<T>(PgConverter converter)
+        => typeof(T).IsEnum && Enum.GetUnderlyingType(typeof(T)) == converter.TypeToConvert && converter is IEnumUnderlyingConverter;
+
+    // Typed enum-underlying helpers. The enum-typed instantiations are reached only via the dispatch sites'
+    // RuntimeFeature.IsDynamicCodeSupported gate, which ILC discharges to false under NAOT — so they don't get
+    // instantiated per enum-T (no viral bloat). Under JIT, RyuJIT folds the typecode switch per concrete T at
+    // codegen time, leaving only the matching case live. T is the enum or (via the converter's own Read/Write)
+    // its underlying primitive; Unsafe.BitCast reinterprets the layout-identical bits — signed and unsigned
+    // alike — without boxing.
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    static T ReadAsEnumUnderlying<T>(PgReader reader)
+        => Type.GetTypeCode(typeof(T)) switch
+        {
+            TypeCode.Int32 or TypeCode.UInt32 => Unsafe.BitCast<int, T>(reader.ReadInt32()),
+            TypeCode.Int64 or TypeCode.UInt64 => Unsafe.BitCast<long, T>(reader.ReadInt64()),
+            TypeCode.Int16 or TypeCode.UInt16 => Unsafe.BitCast<short, T>(reader.ReadInt16()),
+            TypeCode.Byte => Unsafe.BitCast<byte, T>(checked((byte)reader.ReadInt16())),
+            TypeCode.SByte => Unsafe.BitCast<sbyte, T>(checked((sbyte)reader.ReadInt16())),
+            _ => throw new NotSupportedException()
+        };
+
+    static bool IsDbNullAsEnumUnderlying<T>(T? value, object? writeState) => false;
+
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    static Size BindAsEnumUnderlying<T>(in BindContext context, T value, ref object? writeState)
+    {
+        if (context.IsBindOptional)
+            return context.BufferRequirement;
+
+        throw new NotSupportedException();
+    }
+
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    static void WriteAsEnumUnderlying<T>(PgWriter writer, T value)
+    {
+        switch (Type.GetTypeCode(typeof(T)))
+        {
+            case TypeCode.Int32 or TypeCode.UInt32:
+                writer.WriteInt32(Unsafe.BitCast<T, int>(value));
+                break;
+            case TypeCode.Int64 or TypeCode.UInt64:
+                writer.WriteInt64(Unsafe.BitCast<T, long>(value));
+                break;
+            case TypeCode.Int16 or TypeCode.UInt16:
+                writer.WriteInt16(Unsafe.BitCast<T, short>(value));
+                break;
+            case TypeCode.Byte:
+                writer.WriteInt16(Unsafe.BitCast<T, byte>(value));
+                break;
+            case TypeCode.SByte:
+                writer.WriteInt16(Unsafe.BitCast<T, sbyte>(value));
+                break;
+            default: throw new NotSupportedException();
+        }
+    }
+
+    // Known PG wire sizes per .NET underlying type — matches the default Ado mappings. byte/sbyte/short/ushort
+    // → Int2 (2 bytes), int/uint → Int4 (4 bytes), long/ulong → Int8 (8 bytes). PG has no unsigned types, so
+    // unsigned .NET underlyings are bit-reinterpreted onto the signed wire format of the same width.
+    static int WireSize<T>()
+        => Type.GetTypeCode(typeof(T)) switch
+        {
+            TypeCode.Int32 or TypeCode.UInt32 => sizeof(int),
+            TypeCode.Int64 or TypeCode.UInt64 => sizeof(long),
+            TypeCode.Int16 or TypeCode.UInt16 or TypeCode.Byte or TypeCode.SByte => sizeof(short),
+            _ => throw new NotSupportedException()
+        };
+
+    // Typed Enum.ToObject overload — one allocation (the boxed enum), no intermediate boxed underlying.
+    // Used by both the value and nullable converter's AsObject paths.
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    static object ReadAsBoxedEnum<T>(PgReader reader, Type enumType)
+        => Type.GetTypeCode(typeof(T)) switch
+        {
+            TypeCode.Int32 or TypeCode.UInt32 => Enum.ToObject(enumType, reader.ReadInt32()),
+            TypeCode.Int64 or TypeCode.UInt64 => Enum.ToObject(enumType, reader.ReadInt64()),
+            TypeCode.Int16 or TypeCode.UInt16 => Enum.ToObject(enumType, reader.ReadInt16()),
+            TypeCode.Byte => Enum.ToObject(enumType, checked((byte)reader.ReadInt16())),
+            TypeCode.SByte => Enum.ToObject(enumType, checked((sbyte)reader.ReadInt16())),
+            _ => throw new NotSupportedException()
+        };
+}
+
+/// <summary>
+/// Converter for a CLR enum's underlying primitive. Reads/writes the primitive directly using the PG wire format
+/// Npgsql's default mappings use for the corresponding .NET type (byte/sbyte/short → smallint, int → integer,
+/// long → bigint), and re-materializes the boxed value as the enum on the AsObject path via
+/// <see cref="Enum.ToObject(Type, object)"/>. Inherits <see cref="PgBufferedConverter{T}"/> so all per-T async
+/// accessor codegen is provided by the base — only the AsObject read needs an override here. Carrying the enum
+/// type here lets callers holding a non-generic <see cref="PgConverter"/> reference get a correctly-boxed enum.
+/// </summary>
+sealed class EnumUnderlyingConverter<T>(Type enumType) : PgBufferedConverter<T>, IEnumUnderlyingConverter
+    where T : unmanaged, IBinaryInteger<T>
+{
+    public override ConverterDescriptor GetDescriptor(in DescriptorContext context)
+        => ConverterDescriptor.Invariant with { BufferRequirements = BufferRequirements.CreateFixedSize(IEnumUnderlyingConverter.WireSize<T>()) };
+
+    public override T Read(PgReader reader)
+        => IEnumUnderlyingConverter.ReadAsEnumUnderlying<T>(reader);
+
+    public override void Write(PgWriter writer, T value)
+        => IEnumUnderlyingConverter.WriteAsEnumUnderlying(writer, value);
+
+    // Typed Enum.ToObject overload — exactly one allocation per call (the boxed enum), no intermediate boxed
+    // underlying. No async machinery: reads are buffered, result is synchronously available.
+    internal override ValueTask<object?> ReadAsObject(bool async, PgReader reader, CancellationToken cancellationToken)
+        => new(IEnumUnderlyingConverter.ReadAsBoxedEnum<T>(reader, enumType));
+}
+
+/// <summary>
+/// Nullable sibling of <see cref="EnumUnderlyingConverter{T}"/>. Same wire format, same boxing behavior on the
+/// AsObject path (boxed <see cref="Nullable{T}"/> strips the wrapper, so a boxed enum unboxes to TEnum? at the
+/// caller). Read/Write delegate to the shared <see cref="IEnumUnderlyingConverter"/> helpers; the framework's
+/// null-handling stops at the wire-length check, so Read/Write only see non-null values here.
+/// </summary>
+sealed class EnumUnderlyingNullableConverter<T>(Type enumType) : PgBufferedConverter<T?>, IEnumUnderlyingConverter
+    where T : unmanaged, IBinaryInteger<T>
+{
+    public override ConverterDescriptor GetDescriptor(in DescriptorContext context)
+        => ConverterDescriptor.Invariant with { BufferRequirements = BufferRequirements.CreateFixedSize(IEnumUnderlyingConverter.WireSize<T>()) };
+
+    public override T? Read(PgReader reader)
+        => IEnumUnderlyingConverter.ReadAsEnumUnderlying<T>(reader);
+
+    public override void Write(PgWriter writer, T? value)
+        => IEnumUnderlyingConverter.WriteAsEnumUnderlying(writer, value.GetValueOrDefault());
+
+    internal override ValueTask WriteAsObject(bool async, PgWriter writer, object? value, CancellationToken cancellationToken)
+    {
+        // A boxed enum can unbox as its underlying T, but not directly as Nullable<T>.
+        Write(writer, value is null ? null : (T)value);
+        return default;
+    }
+
+    internal override ValueTask<object?> ReadAsObject(bool async, PgReader reader, CancellationToken cancellationToken)
+        => new(IEnumUnderlyingConverter.ReadAsBoxedEnum<T>(reader, enumType));
+}
@@ -6,13 +6,13 @@
 namespace Npgsql.Internal.Converters;
 
 [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)]
-sealed class EnumConverter<TEnum> : PgBufferedConverter<TEnum> where TEnum : struct, Enum
+sealed class PgEnumConverter<TEnum> : PgBufferedConverter<TEnum> where TEnum : struct, Enum
 {
     readonly Dictionary<TEnum, string> _enumToLabel;
     readonly Dictionary<string, TEnum> _labelToEnum;
 
     // Unmapped enums
-    public EnumConverter(Dictionary<Enum, string> enumToLabel, Dictionary<string, Enum> labelToEnum)
+    public PgEnumConverter(Dictionary<Enum, string> enumToLabel, Dictionary<string, Enum> labelToEnum)
     {
         _enumToLabel = new(enumToLabel.Count);
         foreach (var kv in enumToLabel)
@@ -23,7 +23,7 @@ public EnumConverter(Dictionary<Enum, string> enumToLabel, Dictionary<string, En
             _labelToEnum.Add(kv.Key, (TEnum)kv.Value);
     }
 
-    public EnumConverter(Dictionary<TEnum, string> enumToLabel, Dictionary<string, TEnum> labelToEnum)
+    public PgEnumConverter(Dictionary<TEnum, string> enumToLabel, Dictionary<string, TEnum> labelToEnum)
     {
         _enumToLabel = enumToLabel;
         _labelToEnum = labelToEnum;

@@ -34,7 +34,7 @@ protected override Size BindValue(in BindContext context, T value, ref object? w
     public sealed override ValueTask<T> ReadAsync(PgReader reader, CancellationToken cancellationToken = default)
         => new(Read(reader));
 
-    internal sealed override ValueTask<object?> ReadAsObject(bool async, PgReader reader, CancellationToken cancellationToken)
+    internal override ValueTask<object?> ReadAsObject(bool async, PgReader reader, CancellationToken cancellationToken)
         => new(Read(reader));
 
 #pragma warning disable CS0618 // Type or member is obsolete
@@ -47,7 +47,7 @@ public sealed override ValueTask WriteAsync(PgWriter writer, T value, Cancellati
         return new();
     }
 
-    internal sealed override ValueTask WriteAsObject(bool async, PgWriter writer, object? value, CancellationToken cancellationToken)
+    internal override ValueTask WriteAsObject(bool async, PgWriter writer, object? value, CancellationToken cancellationToken)
     {
         Write(writer, (T)value!);
         return new();