Thread: Undocumented count in FORWARD/BACKWARD direction of MOVE statement

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/16/plpgsql-cursors.html
Description:

The documentation shows this example for the MOVE statement:

MOVE FORWARD 2 FROM curs4;

According to the docs, this should not work. The count is documented only
for the directions ABSOLUTE and RELATIVE (which should be enough). "FORWARD
count" and "BACKWARD" count works in MOVE but not in FETCH. I don't know if
this is intentional. However, the docs do not seem to be correct for MOVE
directions.

PG Doc comments form <noreply@postgresql.org> writes:
> The following documentation comment has been logged on the website:
> Page: https://www.postgresql.org/docs/16/plpgsql-cursors.html
> Description:

> The documentation shows this example for the MOVE statement:

> MOVE FORWARD 2 FROM curs4;

> According to the docs, this should not work. The count is documented only
> for the directions ABSOLUTE and RELATIVE (which should be enough). "FORWARD
> count" and "BACKWARD" count works in MOVE but not in FETCH. I don't know if
> this is intentional. However, the docs do not seem to be correct for MOVE
> directions.

Yeah, you're right.  MOVE does not have the restriction about not
taking forms of "direction" that specify multiple rows.  But the
docs just refer you to FETCH which does have that restriction,
so unless you read that as referring to SQL FETCH it's wrong.

I also notice this comment in pl_gram.y:

        /*
         * 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.
         */

It seems to me that it'd be better to surface that in the docs,
that is describe the case as deprecated.

So maybe something like

    MOVE repositions a cursor without retrieving any data.
    MOVE works like the FETCH command, except it only repositions the
    cursor and does not return the row moved to.
    The direction clause can be any of the variants allowed in the SQL
    FETCH command, including those that would 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 without a keyword is deprecated.  (It is ambiguous with
    the case where the direction clause is omitted altogether, and
    hence 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 row to move to.

            regards, tom lane

> On 22 Jul 2024, at 18:24, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> PG Doc comments form <noreply@postgresql.org> writes:
>> The following documentation comment has been logged on the website:
>> Page: https://www.postgresql.org/docs/16/plpgsql-cursors.html
>> Description:
>
>> The documentation shows this example for the MOVE statement:
>
>> MOVE FORWARD 2 FROM curs4;
>
>> According to the docs, this should not work. The count is documented only
>> for the directions ABSOLUTE and RELATIVE (which should be enough). "FORWARD
>> count" and "BACKWARD" count works in MOVE but not in FETCH. I don't know if
>> this is intentional. However, the docs do not seem to be correct for MOVE
>> directions.
>
> Yeah, you're right.  MOVE does not have the restriction about not
> taking forms of "direction" that specify multiple rows.  But the
> docs just refer you to FETCH which does have that restriction,
> so unless you read that as referring to SQL FETCH it's wrong.
>
> I also notice this comment in pl_gram.y:
>
>        /*
>         * 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.
>         */
>
> It seems to me that it'd be better to surface that in the docs,
> that is describe the case as deprecated.
>
> So maybe something like
>
>    MOVE repositions a cursor without retrieving any data.
>    MOVE works like the FETCH command, except it only repositions the
>    cursor and does not return the row moved to.
>    The direction clause can be any of the variants allowed in the SQL
>    FETCH command, including those that would 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 without a keyword is deprecated.  (It is ambiguous with
>    the case where the direction clause is omitted altogether, and
>    hence 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 row to move to.
>
>             regards, tom lane

Yes, that's clearer. Especially referring to SQL FETCH instead of FETCH helps. Therefore I would change FETCH to SQL
FETCHalso in your second paragraph. 

I read FETCH in the current documentation as PL/pgSQL FETCH and therefore checked the list of directions mentioned in
theprevious chapter. 

Thanks, Philipp