Message-ID: <097e693ea6cc3541cbcd72c915d7d492c26930c0.camel@cybertec.at>
Subject: Re: please define 'statement' in the glossary
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: petermittere@gmail.com, pgsql-docs@lists.postgresql.org
Date: Sun, 13 Jul 2025 23:11:14 +0200
In-Reply-To: <270191.1752420426@sss.pgh.pa.us>
References: 
	<175223006802.3157505.14764328206246105568@wrigleys.postgresql.org>
	 <15139c5d218754350e4870062f90ff0e85490290.camel@cybertec.at>
	 <270191.1752420426@sss.pgh.pa.us>
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/097e693ea6cc3541cbcd72c915d7d492c26930c0.camel%40cybertec.at>
Precedence: bulk

On Sun, 2025-07-13 at 11:27 -0400, Tom Lane wrote:
> Laurenz Albe <laurenz.albe@cybertec.at> writes:
> > After looking at the code, I guess what made Tom add the remark in comm=
it
> > eaf8f312c754 was the fact that an SQL statement is not necessarily proc=
essed
> > in a single go: with the extended query protocol (see chapter 52.2.3),
> > there is a "parse", a "bind" and an "execute" message from the client, =
and
> > each one sets the timestamp reported by statement_timestamp() to a new
> > value.  So, technically, statement_timestamp() has a different value wh=
en
> > the statement is parsed than when it is executed.
>=20
> > However, what matters to the client is the value when the statement sta=
rts
> > executing, because that's the value that will be reported.
>=20
> > So I'd argue that we should remove the parenthetical remark.  It confus=
es
> > more than it enlightens, and whoever needs to know that level of detail
> > had better read the code anyway.
>=20
> After re-reading that text, I feel like the parenthetical remark is
> fine, and the real problem is that I used "statement" and "command"
> more or less interchangeably in successive sentences.  Perhaps
> s/command/statement/g throughout the paragraph would improve matters?
> Although "statement message" doesn't feel right, so maybe leave that
> one alone.

Changing "command" to "statement" would be a good move.

I guess I get the remark now: it wants to say that
a) statement_timestamp() shows the time when the client message that
   started the execution of the current SQL statement reached the server
and
b) the timestamp isn't reset for nested statements

Perhaps the remark should say "protocol message" or "frontend-backend
protocol message" to make clear that we are not talking about an
SQL statement here.

Yours,
Laurenz Albe