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
