Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit d2cba4f

Browse files
committed
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
1 parent efcbb76 commit d2cba4f

File tree

2 files changed

+28
-11
lines changed

2 files changed

+28
-11
lines changed

doc/src/sgml/plpgsql.sgml

+23-6
Original file line numberDiff line numberDiff line change
@@ -3409,13 +3409,16 @@ FETCH <optional> <replaceable>direction</replaceable> { FROM | IN } </optional>
34093409
</synopsis>
34103410

34113411
<para>
3412-
<command>FETCH</command> retrieves the next row from the
3412+
<command>FETCH</command> retrieves the next row (in the indicated
3413+
direction) from the
34133414
cursor into a target, which might be a row variable, a record
34143415
variable, or a comma-separated list of simple variables, just like
3415-
<command>SELECT INTO</command>. If there is no next row, the
3416+
<command>SELECT INTO</command>. If there is no suitable row, the
34163417
target is set to NULL(s). As with <command>SELECT
34173418
INTO</command>, the special variable <literal>FOUND</literal> can
3418-
be checked to see whether a row was obtained or not.
3419+
be checked to see whether a row was obtained or not. If no row is
3420+
obtained, the cursor is positioned after the last row or before the
3421+
first row, depending on the movement direction.
34193422
</para>
34203423

34213424
<para>
@@ -3467,11 +3470,25 @@ MOVE <optional> <replaceable>direction</replaceable> { FROM | IN } </optional> <
34673470

34683471
<para>
34693472
<command>MOVE</command> repositions a cursor without retrieving
3470-
any data. <command>MOVE</command> works exactly like the
3473+
any data. <command>MOVE</command> works like the
34713474
<command>FETCH</command> command, except it only repositions the
3472-
cursor and does not return the row moved to. As with <command>SELECT
3475+
cursor and does not return the row moved to.
3476+
The <replaceable>direction</replaceable> clause can be any of the
3477+
variants allowed in the SQL <xref linkend="sql-fetch"/>
3478+
command, including those that can fetch more than one row;
3479+
the cursor is positioned to the last such row.
3480+
(However, the case in which the <replaceable>direction</replaceable>
3481+
clause is simply a <replaceable>count</replaceable> expression with
3482+
no key word is deprecated in <application>PL/pgSQL</application>.
3483+
That syntax is ambiguous with the case where
3484+
the <replaceable>direction</replaceable> clause is omitted
3485+
altogether, and hence it may fail if
3486+
the <replaceable>count</replaceable> is not a constant.)
3487+
As with <command>SELECT
34733488
INTO</command>, the special variable <literal>FOUND</literal> can
3474-
be checked to see whether there was a next row to move to.
3489+
be checked to see whether there was a row to move to. If there is no
3490+
such row, the cursor is positioned after the last row or before the
3491+
first row, depending on the movement direction.
34753492
</para>
34763493

34773494
<para>

src/pl/plpgsql/src/pl_gram.y

+5-5
Original file line numberDiff line numberDiff line change
@@ -3219,11 +3219,11 @@ read_fetch_direction(void)
32193219
{
32203220
/*
32213221
* Assume it's a count expression with no preceding keyword.
3222-
* Note: we allow this syntax because core SQL does, but we don't
3223-
* document it because of the ambiguity with the omitted-direction
3224-
* case. For instance, "MOVE n IN c" will fail if n is a variable.
3225-
* Perhaps this can be improved someday, but it's hardly worth a
3226-
* lot of work.
3222+
* Note: we allow this syntax because core SQL does, but it's
3223+
* ambiguous with the case of an omitted direction clause; for
3224+
* instance, "MOVE n IN c" will fail if n is a variable, because the
3225+
* preceding else-arm will trigger. Perhaps this can be improved
3226+
* someday, but it hardly seems worth a lot of work.
32273227
*/
32283228
plpgsql_push_back_token(tok);
32293229
fetch->expr = read_sql_expression2(K_FROM, K_IN,

0 commit comments

Comments
 (0)