From: Tom Lane <tgl@sss.pgh.pa.us>
To: Laurenz Albe <laurenz.albe@cybertec.at>
cc: "David G. Johnston" <david.g.johnston@gmail.com>, petermittere@gmail.com,
        pgsql-docs@lists.postgresql.org
Subject: Re: please define 'statement' in the glossary
In-reply-to: <ec1e6bb700f9eefceea0648656b38ab223c14c54.camel@cybertec.at>
References: 
 <175223006802.3157505.14764328206246105568@wrigleys.postgresql.org>
 <15139c5d218754350e4870062f90ff0e85490290.camel@cybertec.at>
 <270191.1752420426@sss.pgh.pa.us>
 <097e693ea6cc3541cbcd72c915d7d492c26930c0.camel@cybertec.at>
 <456003.1752442676@sss.pgh.pa.us> <458204.1752443813@sss.pgh.pa.us>
 <CAKFQuwa4VMoHehuN5qCX5Jv15ZahTJ00jxMu4mbtYNHbJ4PXOA@mail.gmail.com>
 <ec1e6bb700f9eefceea0648656b38ab223c14c54.camel@cybertec.at>
Comments: In-reply-to Laurenz Albe <laurenz.albe@cybertec.at>
	message dated "Mon, 14 Jul 2025 08:24:53 +0200"
MIME-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
Content-ID: <685002.1752506254.1@sss.pgh.pa.us>
Content-Transfer-Encoding: quoted-printable
Date: Mon, 14 Jul 2025 11:17:34 -0400
Message-ID: <685003.1752506254@sss.pgh.pa.us>
Archived-At: 
 <https://www.postgresql.org/message-id/685003.1752506254%40sss.pgh.pa.us>
Precedence: bulk

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=C2=A0involving=C2=A0=
the fe/be protocol
>> in the SQL portion of the documentation - rightly considering (IMO) tho=
se to be
>> implementation details (e.g., we don't even directly mention simple pro=
tocol 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 tha=
t 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.

			regards, tom lane