Re: please define 'statement' in the glossary

On Fri, 2025-07-11 at 10:34 +0000, PG Doc comments form wrote:
> the glossary (https://www.postgresql.org/docs/current/glossary.html) does
> not define 'statement' but a definition would be important to understand
> other chapters such as this sentence: "statement_timestamp() returns the
> start time of the current statement (more specifically, the time of receipt
> of the latest command message from the client)." The sentence is from
> https://www.postgresql.org/docs/17/functions-datetime.html#FUNCTIONS-DATETIME-CURRENT.
> From the same page is this snippet: "start of current statement", in Table
> 9.33. Date/Time Functions.
> It seems 'statement' can mean different things such as 'one operation, such
> as a SELECT statement', but it can also mean 'all operations since the last
> command message from the client, which can be several SELECTs'.

In the setting of a relational database system like PostgreSQL, "statement"
means "SQL statement".  I don't think that that requires a glossary entry.
"SQL statement" is pretty well defined.

I guess your difficulties come from the remark in parentheses, which is
intended to clarify, but clearly does not quite succeed in that.

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.

Yours,
Laurenz Albe