From 9aa644f92959eca29680595e725a6e71b273f08d Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Mon, 22 Jul 2024 19:43:12 -0400 Subject: [PATCH] Doc: improve description of plpgsql's FETCH and MOVE commands. We were not being clear about which variants of the "direction" clause are permitted in MOVE. Also, the text seemed to be written with only the FETCH/MOVE NEXT case in mind, so it didn't apply very well to other variants. Also, document that "MOVE count IN cursor" only works if count is a constant. This is not the whole truth, because some other cases such as a parenthesized expression will also work, but we want to push people to use "MOVE FORWARD count" instead. The constant case is enough to cover what we allow in plain SQL, and that seems sufficient to claim support for. Update a comment in pl_gram.y claiming that we don't document that point. Per gripe from Philipp Salvisberg. Discussion: https://postgr.es/m/172155553388.702.7932496598218792085@wrigleys.postgresql.org --- doc/src/sgml/plpgsql.sgml | 29 +++++++++++++++++++++++------ src/pl/plpgsql/src/pl_gram.y | 10 +++++----- 2 files changed, 28 insertions(+), 11 deletions(-) diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml index b18e242fde8..936de410a93 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -3358,13 +3358,16 @@ FETCH direction { FROM | IN } - FETCH retrieves the next row from the + FETCH retrieves the next row (in the indicated + direction) from the cursor into a target, which might be a row variable, a record variable, or a comma-separated list of simple variables, just like - SELECT INTO. If there is no next row, the + SELECT INTO. If there is no suitable row, the target is set to NULL(s). As with SELECT INTO, the special variable FOUND can - be checked to see whether a row was obtained or not. + be checked to see whether a row was obtained or not. If no row is + obtained, the cursor is positioned after the last row or before the + first row, depending on the movement direction. @@ -3416,11 +3419,25 @@ MOVE direction { FROM | IN } < MOVE repositions a cursor without retrieving - any data. MOVE works exactly like the + any data. MOVE works like the FETCH command, except it only repositions the - cursor and does not return the row moved to. As with SELECT + cursor and does not return the row moved to. + The direction clause can be any of the + variants allowed in the SQL + command, including those that can fetch more than one row; + the cursor is positioned to the last such row. + (However, the case in which the direction + clause is simply a count expression with + no key word is deprecated in PL/pgSQL. + That syntax is ambiguous with the case where + the direction clause is omitted + altogether, and hence it may fail if + the count is not a constant.) + As with SELECT INTO, the special variable FOUND can - be checked to see whether there was a next row to move to. + be checked to see whether there was a row to move to. If there is no + such row, the cursor is positioned after the last row or before the + first row, depending on the movement direction. diff --git a/src/pl/plpgsql/src/pl_gram.y b/src/pl/plpgsql/src/pl_gram.y index c7b3a50a705..8d27edbf07b 100644 --- a/src/pl/plpgsql/src/pl_gram.y +++ b/src/pl/plpgsql/src/pl_gram.y @@ -3218,11 +3218,11 @@ read_fetch_direction(void) { /* * Assume it's a count expression with no preceding keyword. - * Note: we allow this syntax because core SQL does, but we don't - * document it because of the ambiguity with the omitted-direction - * case. For instance, "MOVE n IN c" will fail if n is a variable. - * Perhaps this can be improved someday, but it's hardly worth a - * lot of work. + * Note: we allow this syntax because core SQL does, but it's + * ambiguous with the case of an omitted direction clause; for + * instance, "MOVE n IN c" will fail if n is a variable, because the + * preceding else-arm will trigger. Perhaps this can be improved + * someday, but it hardly seems worth a lot of work. */ plpgsql_push_back_token(tok); fetch->expr = read_sql_expression2(K_FROM, K_IN,