Re: please define 'statement' in the glossary
| От | P M |
|---|---|
| Тема | Re: please define 'statement' in the glossary |
| Дата | |
| Msg-id | CAETs_odae+WGfVdDj3xoiJ1JGiF0axAJqz3759c_GcPpDpPKAA@mail.gmail.com обсуждение исходный текст |
| Ответ на | Re: please define 'statement' in the glossary (Laurenz Albe <laurenz.albe@cybertec.at>) |
| Список | pgsql-docs |
Hello,
I think you are saying that 'statement' in the documentation shall mean 'SQL statement' and not 'the time of receipt of the latest command message from the client'.
I also think that statement_timestamp() will keep its name, even though the name can be seen as misleading by some.
I therefore suggest to change the wording in the table on top
from
"Current date and time (start of current statement)"
to
"Current date and time (receipt of the latest command message from the client)"
and to change the explanatory sentence further down
from
"statement_timestamp() returns the start time of the current statement (more specifically, the time of receipt of the latest command message from the client)."
to
"statement_timestamp() returns the time of receipt of the latest command message from the client."
And leave it to the reader to discover 'well that function's naming is a bit unfortunate', but not elaborate on that in the documentation.
A bonus would be to define 'command message' in the glossary.
Side note: This is the SQL that I used to teach myself that 'statement_timestamp' does not mean 'the data in the DB is seen by the calling statement as of this time' but that it just means when the last message from the client arrived:
--1
do
$body$
begin
drop table if exists st;
create table st(
id serial primary key,
started_at timestamp with time zone
);
insert into st(started_at) values(statement_timestamp());
execute pg_sleep(3);
insert into st(started_at) values(statement_timestamp());
execute pg_sleep(3);
insert into st(started_at) values(statement_timestamp());
end;
$body$;
select * from st;
--id|started_at |
----+-----------------------------+
-- 1|2025-07-10 10:50:55.424 +0000|
-- 2|2025-07-10 10:50:55.424 +0000|
-- 3|2025-07-10 10:50:55.424 +0000|
--2
drop table if exists st;
create table st(
id serial primary key,
started_at timestamp with time zone
);
begin;
insert into st(started_at) values(statement_timestamp());
select pg_sleep(3);
insert into st(started_at) values(statement_timestamp());
select pg_sleep(3);
insert into st(started_at) values(statement_timestamp());
end;
select * from st;
--id|started_at |
----+-----------------------------+
-- 1|2025-07-10 10:58:22.397 +0000|
-- 2|2025-07-10 10:58:25.413 +0000|
-- 3|2025-07-10 10:58:28.429 +0000|
Hope this helps, thank you for all your thoughts on the matter
Kind regards
Peter
On Mon, Jul 14, 2025 at 8:24 AM Laurenz Albe <laurenz.albe@cybertec.at> wrote:
On Sun, 2025-07-13 at 17:32 -0700, David G. Johnston wrote:
> On Sun, Jul 13, 2025 at 2:57 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> > ... so concretely, about like this?
I am fine with the patch as it is.
> 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.
But there is also nothing evil about hints for the initiated, lest they are
of a kind that can confuse beginners.
> I'd be ok if we'd limit this to a
> distinction between the simple protocol and the extended protocol since, as a
> volatile function, it isn't even like statement_timestamp can be seen in extended
> protocol aside from when execute is sent. So the special case where it doesn't
> behave as expected is a simple protocol multi-statement command.
It is STABLE, not VOLATILE, as befits the name, but yes, I see your point.
> An example in
> psql would serve to make this much more clear than any wording can do.
> Possibly added here or as part of the existing documentation that 'psql -c'
> points to [1]. Which probably could be pointed to from here as well.
Perhaps - but I feel uneasy about adding even more documentation. If we show
how statement_timestamp() does *not* work as expected with a multi-statement
command, we might confuse the reader even more. With the improved parenthetical
remark, I'd expect anybody with superficial knowledge of PostgreSQL to just
skip over the remark, with little damage done ("Ah, some comment about internals
that they couldn't help making.").
But if we add examples, we should be ready to explain in depth why it is the way
it is, and then we would have to get even deeper into the discussion of the
protocol that you bemoaned at the beginning of your mail.
> Seems also like maybe SPI should be mentioned explicitly here since it seems to
> act like a client in a relevant way. I'm assuming a statement_timestamp executed
> within a function will return the same timestamp the calling statement would.
Well, in this case it doesn't act like a client. That would mean dragging up
even more details from a section of the documentation that is only of interest
to hackers.
I think we should let the lions sleep. The documentation of the built-in
functions is mostly of interest to application developers and writers of SQL
and PL/pgSQL, and expanding on SPI and the client-server protocol isn't what's
asked for here. The documentation should be detailed, but there is a fine
line that you shouldn't cross if you don't want to confuse the reader.
The parenthetical remark is hopefully enough to get the interested reader
on the right track.
Yours,
Laurenz Albe
В списке pgsql-docs по дате отправления: