Message-ID: <ec1e6bb700f9eefceea0648656b38ab223c14c54.camel@cybertec.at>
Subject: Re: please define 'statement' in the glossary
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: "David G. Johnston" <david.g.johnston@gmail.com>, Tom Lane
	 <tgl@sss.pgh.pa.us>
Cc: petermittere@gmail.com, pgsql-docs@lists.postgresql.org
Date: Mon, 14 Jul 2025 08:24:53 +0200
In-Reply-To: 
 <CAKFQuwa4VMoHehuN5qCX5Jv15ZahTJ00jxMu4mbtYNHbJ4PXOA@mail.gmail.com>
References: 
	<175223006802.3157505.14764328206246105568@wrigleys.postgresql.org>
	 <15139c5d218754350e4870062f90ff0e85490290.camel@cybertec.at>
	 <270191.1752420426@sss.pgh.pa.us>
	 <097e693ea6cc3541cbcd72c915d7d492c26930c0.camel@cybertec.at>
	 <456003.1752442676@sss.pgh.pa.us> <458204.1752443813@sss.pgh.pa.us>
	 <CAKFQuwa4VMoHehuN5qCX5Jv15ZahTJ00jxMu4mbtYNHbJ4PXOA@mail.gmail.com>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
User-Agent: Evolution 3.56.2 (3.56.2-1.fc42) 
MIME-Version: 1.0
Archived-At: 
 <https://www.postgresql.org/message-id/ec1e6bb700f9eefceea0648656b38ab223c14c54.camel%40cybertec.at>
Precedence: bulk

On Sun, 2025-07-13 at 17:32 -0700, David G. Johnston wrote:
> On Sun, Jul 13, 2025 at 2:57=E2=80=AFPM Tom Lane <tgl@sss.pgh.pa.us> wrot=
e:
> > ... so concretely, about like this?

I am fine with the patch as it is.

> We seldom if ever resort to including descriptions=C2=A0involving=C2=A0th=
e fe/be protocol
> in the SQL portion of the documentation - rightly considering (IMO) those=
 to be
> implementation details (e.g., we don't even directly mention simple proto=
col in
> "psql -c" - though we do link to it under "multi-statement commands").
> Is there no way to avoid that here?

Well, I would have gladly removed the parenthetical remark, thinking that i=
f
somebody needed to know precisely, she'd read up in the code.
But there is also nothing evil about hints for the initiated, lest they are
of a kind that can confuse beginners.

>                                   =C2=A0  I'd be ok if we'd limit this to=
 a
> distinction between the simple protocol and the extended protocol since, =
as a
> volatile function, it isn't even like statement_timestamp can be seen in =
extended
> protocol aside from when execute is sent.=C2=A0 So the special case where=
 it doesn't
> behave as expected is a simple protocol multi-statement command.

It is STABLE, not VOLATILE, as befits the name, but yes, I see your point.

>                                                                 =C2=A0 An=
 example in
> psql would serve to make this much more clear than any wording can do.
> Possibly added here or as part of the existing documentation that 'psql -=
c'
> points to [1].=C2=A0 Which probably could be pointed to from here as well=
.

Perhaps - but I feel uneasy about adding even more documentation.  If we sh=
ow
how statement_timestamp() does *not* work as expected with a multi-statemen=
t
command, we might confuse the reader even more.  With the improved parenthe=
tical
remark, I'd expect anybody with superficial knowledge of PostgreSQL to just
skip over the remark, with little damage done ("Ah, some comment about inte=
rnals
that they couldn't help making.").

But if we add examples, we should be ready to explain in depth why it is th=
e way
it is, and then we would have to get even deeper into the discussion of the
protocol that you bemoaned at the beginning of your mail.

> Seems also like maybe SPI should be mentioned explicitly here since it se=
ems to
> act like a client in a relevant way.=C2=A0 I'm assuming a statement_times=
tamp executed
> within a function will return the same timestamp the calling statement wo=
uld.

Well, in this case it doesn't act like a client.  That would mean dragging =
up
even more details from a section of the documentation that is only of inter=
est
to hackers.

I think we should let the lions sleep.  The documentation of the built-in
functions is mostly of interest to application developers and writers of SQ=
L
and PL/pgSQL, and expanding on SPI and the client-server protocol isn't wha=
t's
asked for here.  The documentation should be detailed, but there is a fine
line that you shouldn't cross if you don't want to confuse the reader.

The parenthetical remark is hopefully enough to get the interested reader
on the right track.

Yours,
Laurenz Albe