From 78ff6e0fab3fa2a7064ef8aadaa9e7f87ed5f4a6 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 998d71029f1..bf9076bb7df 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -3230,13 +3230,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. @@ -3288,11 +3291,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 14c943cfe7e..7078556412e 100644 --- a/src/pl/plpgsql/src/pl_gram.y +++ b/src/pl/plpgsql/src/pl_gram.y @@ -3150,11 +3150,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,