Fix Stringer types encoded as text instead of numeric value in composite fields

Named integer types implementing fmt.Stringer (e.g. protobuf enums) were
encoded using their String() output instead of their numeric value when used
inside composite type fields. This happened because TryWrapBuiltinTypeEncodePlan
matched fmt.Stringer before TryWrapFindUnderlyingTypeEncodePlan could convert
the type to its underlying integer.

Extract fmt.Stringer handling into a new TryWrapStringerEncodePlan function that
runs after TryWrapFindUnderlyingTypeEncodePlan. The wrapper loop's existing
"first successful recursive plan wins" semantics ensures the right behavior:
numeric codecs match for numeric OIDs, Stringer is used as fallback for text OIDs.

Fixes #2527

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jackc

pgtype/composite_test.go

@@ -49,6 +49,67 @@ create type ct_test as (
 	})
 }
 
+// stringerInt32 is a custom int32 type that implements fmt.Stringer, similar to protobuf enums.
+type stringerInt32 int32
+
+const (
+	stringerInt32Foo stringerInt32 = 100
+	stringerInt32Bar stringerInt32 = 200
+)
+
+func (s stringerInt32) String() string {
+	switch s {
+	case stringerInt32Foo:
+		return "FOO"
+	case stringerInt32Bar:
+		return "BAR"
+	default:
+		return "UNKNOWN"
+	}
+}
+
+// https://github.com/jackc/pgx/discussions/2527
+func TestCompositeCodecTranscodeWithStringerInt(t *testing.T) {
+	defaultConnTestRunner.RunTest(context.Background(), t, func(ctx context.Context, t testing.TB, conn *pgx.Conn) {
+		_, err := conn.Exec(ctx, `drop type if exists ct_stringer_test;
+
+create type ct_stringer_test as (
+	a text,
+	b smallint
+);`)
+		require.NoError(t, err)
+		defer conn.Exec(ctx, "drop type ct_stringer_test")
+
+		dt, err := conn.LoadType(ctx, "ct_stringer_test")
+		require.NoError(t, err)
+		conn.TypeMap().RegisterType(dt)
+
+		formats := []struct {
+			name string
+			code int16
+		}{
+			{name: "TextFormat", code: pgx.TextFormatCode},
+			{name: "BinaryFormat", code: pgx.BinaryFormatCode},
+		}
+
+		// Pass the same stringerInt32 value for both fields. The text field should get the Stringer value
+		// ("BAR") and the smallint field should get the integer value (200).
+		for _, format := range formats {
+			var a string
+			var b int16
+
+			err := conn.QueryRow(ctx, "select $1::ct_stringer_test", pgx.QueryResultFormats{format.code},
+				pgtype.CompositeFields{stringerInt32Bar, stringerInt32Bar},
+			).Scan(
+				pgtype.CompositeFields{&a, &b},
+			)
+			require.NoErrorf(t, err, "%v", format.name)
+			require.EqualValuesf(t, "BAR", a, "%v", format.name)
+			require.EqualValuesf(t, 200, b, "%v", format.name)
+		}
+	})
+}
+
 type point3d struct {
 	X, Y, Z float64
 }

pgtype/pgtype.go

@@ -243,6 +243,7 @@ func NewMap() *Map {
 			TryWrapDerefPointerEncodePlan,
 			TryWrapBuiltinTypeEncodePlan,
 			TryWrapFindUnderlyingTypeEncodePlan,
+			TryWrapStringerEncodePlan,
 			TryWrapStructEncodePlan,
 			TryWrapSliceEncodePlan,
 			TryWrapMultiDimSliceEncodePlan,
@@ -1446,6 +1447,24 @@ func TryWrapFindUnderlyingTypeEncodePlan(value any) (plan WrappedEncodePlanNextS
 	return nil, nil, false
 }
 
+// TryWrapStringerEncodePlan tries to wrap a fmt.Stringer type with a wrapper that provides TextValuer. This is
+// intentionally a separate function from TryWrapBuiltinTypeEncodePlan so it can be ordered after
+// TryWrapFindUnderlyingTypeEncodePlan. This ensures that named types with an underlying builtin type (e.g. type MyEnum
+// int32 with a String() method) prefer encoding via the underlying type's codec (e.g. as an integer) rather than via
+// Stringer. Stringer is only used as a fallback when no type-specific encoding plan succeeds.
+// (https://github.com/jackc/pgx/discussions/2527)
+func TryWrapStringerEncodePlan(value any) (plan WrappedEncodePlanNextSetter, nextValue any, ok bool) {
+	if _, ok := value.(driver.Valuer); ok {
+		return nil, nil, false
+	}
+
+	if s, ok := value.(fmt.Stringer); ok {
+		return &wrapFmtStringerEncodePlan{}, fmtStringerWrapper{s}, true
+	}
+
+	return nil, nil, false
+}
+
 type WrappedEncodePlanNextSetter interface {
 	SetNext(EncodePlan)
 	EncodePlan
@@ -1506,8 +1525,6 @@ func TryWrapBuiltinTypeEncodePlan(value any) (plan WrappedEncodePlanNextSetter,
 		return &wrapByte16EncodePlan{}, byte16Wrapper(value), true
 	case []byte:
 		return &wrapByteSliceEncodePlan{}, byteSliceWrapper(value), true
-	case fmt.Stringer:
-		return &wrapFmtStringerEncodePlan{}, fmtStringerWrapper{value}, true
 	}
 
 	return nil, nil, false