Laurenz Albe <laurenz.albe@cybertec.at> writes: > On Sun, 2025-07-13 at 17:32 -0700, David G. Johnston wrote: >> We seldom if ever resort to including descriptions involving the 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 protocol 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 if > somebody needed to know precisely, she'd read up in the code.
The point that I wanted to convey in this para is that statement_timestamp() advances when we receive a command from the client. I don't think that that concept is too deep for the average user, we just need to choose the right words to convey it. Sadly, "SQL statement" doesn't have the right connotations, since for example a command within a SQL-language function is surely a "SQL statement" for most purposes. We're stuck with the function name, but how can we explain it?
I understand David's allergy to mentioning the wire protocol. Would "client message" be better than "protocol message"? I also still like "command message", even if we're avoiding the word "command" elsewhere in the para.
I dislike the word message.
It would be nice if we could say/document: Command means top-level SQL; Statement references a sub-component of a command.
statement_timestamp() returns the start time of the current top-level command being executed (but see the note below). statement_timestamp() and transaction_timestamp() return the same value during the first command of a transaction, but the statement_timeout will normally advance for each subsequent command therein.
NOTE: When sending multiple commands in the same physical query (see 53.2.2.1) all included top-level commands will see the same statement_timestamp() value.
I would then add an example In 53.2.2.1 showing this happening using "psql -c"
