Content-Type: text/plain;
	charset=us-ascii
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3774.600.62\))
Subject: Re: Undocumented count in FORWARD/BACKWARD direction of MOVE
 statement
From: Philipp Salvisberg <philipp.salvisberg@gmail.com>
In-Reply-To: <893915.1721665475@sss.pgh.pa.us>
Date: Mon, 22 Jul 2024 19:49:40 +0200
Cc: pgsql-docs@lists.postgresql.org
Content-Transfer-Encoding: quoted-printable
Message-Id: <A8243675-06E2-4591-AF12-10C4A7BD3A82@gmail.com>
References: <172155553388.702.7932496598218792085@wrigleys.postgresql.org>
 <893915.1721665475@sss.pgh.pa.us>
To: Tom Lane <tgl@sss.pgh.pa.us>
Archived-At: 
 <https://www.postgresql.org/message-id/A8243675-06E2-4591-AF12-10C4A7BD3A82%40gmail.com>
Precedence: bulk


> On 22 Jul 2024, at 18:24, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>=20
> 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:
>=20
>> The documentation shows this example for the MOVE statement:
>=20
>> MOVE FORWARD 2 FROM curs4;
>=20
>> 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.
>=20
> 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.
>=20
> I also notice this comment in pl_gram.y:
>=20
>        /*
>         * 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.
>         */
>=20
> It seems to me that it'd be better to surface that in the docs,
> that is describe the case as deprecated.
>=20
> So maybe something like
>=20
>    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.
>=20
> 			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=