Re: please define 'statement' in the glossary

Поиск
Список
Период
Сортировка
От David G. Johnston
Тема Re: please define 'statement' in the glossary
Дата
Msg-id CAKFQuwYzod+L_vjOuWz8OAte2SoS5V5ByOGfhDx1-ubvHTb11g@mail.gmail.com
обсуждение исходный текст
Ответ на Re: please define 'statement' in the glossary  (Tom Lane <tgl@sss.pgh.pa.us>)
Ответы Re: please define 'statement' in the glossary
Re: please define 'statement' in the glossary
Список pgsql-docs
On Mon, Jul 14, 2025 at 8:17 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
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"


David J.

В списке pgsql-docs по дате отправления: