Send Describe in ExecStatement when cached fields are empty

PgConn.ExecStatement skipped the Describe portal message and used the
cached StatementDescription.Fields. As with Pipeline.SendQueryStatement,
empty cached fields can mean the result set was not known at prepare
time, e.g. a FETCH from a cursor that did not exist yet. Send a Describe
in that case so the server supplies the actual row description at
execution time.

#2626

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: jackc

pgconn/pgconn.go

@@ -1303,7 +1303,9 @@ func (pgConn *PgConn) ExecPrepared(ctx context.Context, stmtName string, paramVa
 //
 // This differs from [PgConn.ExecPrepared] in that it takes a [*StatementDescription] instead of the prepared statement name.
 // Because it has the [*StatementDescription] it can avoid the Describe Portal message that [PgConn.ExecPrepared] must send to get
-// the result column descriptions.
+// the result column descriptions. However, if the statement description has no fields then a Describe is still sent, as
+// an empty Fields may mean the results were not knowable at prepare time, e.g. a FETCH from a cursor that did not exist
+// yet.
 //
 // paramValues are the parameter values. It must be encoded in the format given by paramFormats.
 //
@@ -1364,7 +1366,10 @@ func (pgConn *PgConn) execExtendedPrefix(ctx context.Context, paramValues [][]by
 }
 
 func (pgConn *PgConn) execExtendedSuffix(result *ResultReader, statementDescription *StatementDescription, resultFormats []int16) {
-	if statementDescription == nil {
+	if statementDescription == nil || len(statementDescription.Fields) == 0 {
+		// The cached field descriptions are missing or empty. Empty field descriptions can occur when the statement's
+		// result set was not known at prepare time, e.g. a FETCH from a cursor that did not exist yet. Send a Describe
+		// so the server supplies the actual row description when the statement is executed.
 		pgConn.frontend.SendDescribe(&pgproto3.Describe{ObjectType: 'P'})
 	}
 	pgConn.frontend.SendExecute(&pgproto3.Execute{})

pgconn/pgconn_test.go

@@ -1711,6 +1711,49 @@ func TestConnExecStatement(t *testing.T) {
 	ensureConnValid(t, pgConn)
 }
 
+// https://github.com/jackc/pgx/issues/2626
+func TestConnExecStatementCursorFetch(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
+	defer cancel()
+
+	pgConn, err := pgconn.Connect(ctx, os.Getenv("PGX_TEST_DATABASE"))
+	require.NoError(t, err)
+	defer closeConn(t, pgConn)
+
+	if pgConn.ParameterStatus("crdb_version") != "" {
+		t.Skip("Server does not support cursors in implicit transactions")
+	}
+
+	// Prepare the FETCH before the cursor exists. The server describes the result as NoData so the statement
+	// description has no fields. The actual fields are only known at execution time.
+	sd, err := pgConn.Prepare(ctx, "ps_fetch", `fetch all in "exec_statement_cursor"`, nil)
+	require.NoError(t, err)
+	require.Empty(t, sd.Fields)
+
+	// DECLARE CURSOR requires an explicit transaction block.
+	_, err = pgConn.Exec(ctx, "begin").ReadAll()
+	require.NoError(t, err)
+
+	_, err = pgConn.Exec(ctx, `declare "exec_statement_cursor" cursor for select n, n::text from generate_series(1, 3) n`).ReadAll()
+	require.NoError(t, err)
+
+	result := pgConn.ExecStatement(ctx, sd, nil, nil, nil).Read()
+	require.NoError(t, result.Err)
+	require.Len(t, result.FieldDescriptions, 2)
+	require.Equal(t, uint32(pgtype.Int4OID), result.FieldDescriptions[0].DataTypeOID)
+	require.Equal(t, uint32(pgtype.TextOID), result.FieldDescriptions[1].DataTypeOID)
+	require.Len(t, result.Rows, 3)
+	require.Equal(t, "1", string(result.Rows[0][0]))
+	require.Equal(t, "3", string(result.Rows[2][1]))
+
+	_, err = pgConn.Exec(ctx, "rollback").ReadAll()
+	require.NoError(t, err)
+
+	ensureConnValid(t, pgConn)
+}
+
 type byteCounterConn struct {
 	conn         net.Conn
 	bytesRead    int

query_test.go

@@ -72,6 +72,53 @@ func TestConnQueryRowsFieldDescriptionsBeforeNext(t *testing.T) {
 	assert.Equal(t, "msg", rows.FieldDescriptions()[0].Name)
 }
 
+// https://github.com/jackc/pgx/issues/2626
+func TestConnQueryPreparedCursorFetch(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
+	defer cancel()
+
+	conn := mustConnectString(t, os.Getenv("PGX_TEST_DATABASE"))
+	defer closeConn(t, conn)
+
+	pgxtest.SkipCockroachDB(t, conn, "Server does not support cursors in implicit transactions")
+
+	// Prepare the FETCH before the cursor exists. The server describes the result as NoData so the statement
+	// description has no fields. The actual fields are only known at execution time.
+	sd, err := conn.Prepare(ctx, "fetch_cursor", `fetch all in "query_cursor"`)
+	require.NoError(t, err)
+	require.Empty(t, sd.Fields)
+
+	tx, err := conn.Begin(ctx)
+	require.NoError(t, err)
+	defer tx.Rollback(ctx)
+
+	_, err = tx.Exec(ctx, `declare "query_cursor" cursor for select n, n::text as str from generate_series(1, 3) n`)
+	require.NoError(t, err)
+
+	rows, err := tx.Query(ctx, "fetch_cursor")
+	require.NoError(t, err)
+
+	fds := rows.FieldDescriptions()
+	require.Len(t, fds, 2)
+	require.Equal(t, "n", fds[0].Name)
+	require.Equal(t, "str", fds[1].Name)
+
+	var ns []int32
+	var strs []string
+	for rows.Next() {
+		var n int32
+		var str string
+		require.NoError(t, rows.Scan(&n, &str))
+		ns = append(ns, n)
+		strs = append(strs, str)
+	}
+	require.NoError(t, rows.Err())
+	require.Equal(t, []int32{1, 2, 3}, ns)
+	require.Equal(t, []string{"1", "2", "3"}, strs)
+}
+
 func TestConnQueryWithoutResultSetCommandTag(t *testing.T) {
 	t.Parallel()