Re: please define 'statement' in the glossary

On Mon, Jul 14, 2025 at 10:09 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:

> "David G. Johnston" <david.g.johnston@gmail.com> writes:
> > Ok.  That explains why "statement_timestamp() and transaction_timestamp()
> > return the same value during the first command of a transaction," isn't
> > just stating the obvious.  transaction_timestamp() literally returns the
> > value statement_timestamp().
>
> Right.  I'm tempted to be more explicit about that, along the lines of
>
>      <function>statement_timestamp()</function> and
> <function>transaction_timestamp()</function>
> -    return the same value during the first statement of a transaction,
> but might
> -    differ during subsequent statements.
> +    return the same value during the first statement of a transaction,
> +    because the transaction timestamp is set by copying the statement
> +    timestamp when a new transaction starts.
>
> I didn't include that change below though; perhaps it has too much
> whiff of implementation detail.
>
> > I'm fine with this entire section assuming/stating that extended protocol
> > is in effect and that 53.2.2.1 explains how these behave when executing a
> > multi-statement simple protocol "script".
>
> It's incorrect to claim that this only applies to extended protocol,
> and besides I thought you didn't want to mention protocol details
> here.


The boundary for me is, we can/need to make it clear that there are two
modes in which queries can be sent: simple and extended/normal.  We call
the first one "multi-query strings" in psql which probably suffices, but
the name "simple" is fine.  It's the mention of "messages" that I consider
an implementation detail.

  I can't argue with documenting it in the protocol chapter
> though.


That paragraph is good.

So about like this?
>
>
If we accept that we use the words statement and command interchangeably
then the sole remaining use of command here sticks out because now we have
to explain why commands are different from statements.  I'd rather just
remove the parenthetical.  It's poorly clarifying a point that it seems you
don't want to clarify more fully here.

Instead of:
<function>statement_timestamp()</function> returns the start time of the
current
     statement (more specifically, the time of receipt of the latest command
-    message from the client).
+    from the client).

Maybe:
<function>statement_timestamp()</function> returns the start time of the
current client-issued statement (technically, query).

David J.