Re: please define 'statement' in the glossary

Tom Lane <tgl@sss.pgh.pa.us>

From: Tom Lane <tgl@sss.pgh.pa.us>
To: Laurenz Albe <laurenz.albe@cybertec.at>
Cc: petermittere@gmail.com, pgsql-docs@lists.postgresql.org
Date: 2025-07-13T15:27:06Z
Lists: pgsql-docs
Laurenz Albe <laurenz.albe@cybertec.at> writes:
> After looking at the code, I guess what made Tom add the remark in commit
> eaf8f312c754 was the fact that an SQL statement is not necessarily processed
> 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 when
> the statement is parsed than when it is executed.

> However, what matters to the client is the value when the statement starts
> executing, because that's the value that will be reported.

> So I'd argue that we should remove the parenthetical remark.  It confuses
> more than it enlightens, and whoever needs to know that level of detail
> had better read the code anyway.

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.

			regards, tom lane



Commits

  1. Doc: clarify description of current-date/time functions.

  2. Some editorial work on the documentation of the current-date/time