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.a...@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 <t...@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
>
