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

> On 22 Jul 2024, at 18:24, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
>
> 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

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

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

Thanks, Philipp