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

PG Doc comments form <noreply(at)postgresql(dot)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