From: Philipp Salvisberg <philipp.salvisberg@gmail.com>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Undocumented count in FORWARD/BACKWARD direction of MOVE statement
Date: Mon, 22 Jul 2024 19:49:40 +0200
Message-ID: <A8243675-06E2-4591-AF12-10C4A7BD3A82@gmail.com> (raw)
In-Reply-To: <893915.1721665475@sss.pgh.pa.us>
References: <172155553388.702.7932496598218792085@wrigleys.postgresql.org>
<893915.1721665475@sss.pgh.pa.us>
> 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 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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: philipp.salvisberg@gmail.com, tgl@sss.pgh.pa.us, pgsql-docs@lists.postgresql.org
Subject: Re: Undocumented count in FORWARD/BACKWARD direction of MOVE statement
In-Reply-To: <A8243675-06E2-4591-AF12-10C4A7BD3A82@gmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox