On Mon, Jul 14, 2025 at 8:17 AM Tom Lane <t...@sss.pgh.pa.us> wrote:
> Laurenz Albe <laurenz.a...@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" David J.
