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
