Re: please define 'statement' in the glossary

On Mon, Jul 14, 2025 at 8:17 AM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> Laurenz Albe <laurenz(dot)albe(at)cybertec(dot)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.