agora inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedFrom: Laurenz Albe <laurenz.albe@cybertec.at>
To: David G. Johnston <david.g.johnston@gmail.com>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: petermittere@gmail.com
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: please define 'statement' in the glossary
Date: Mon, 14 Jul 2025 08:24:53 +0200
Message-ID: <ec1e6bb700f9eefceea0648656b38ab223c14c54.camel@cybertec.at> (raw)
In-Reply-To: <CAKFQuwa4VMoHehuN5qCX5Jv15ZahTJ00jxMu4mbtYNHbJ4PXOA@mail.gmail.com>
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>
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
view thread (21+ messages) latest in thread
Message-ID: <ec1e6bb700f9eefceea0648656b38ab223c14c54.camel@cybertec.at>
Permalink: ../ec1e6bb700f9eefceea0648656b38ab223c14c54.camel@cybertec.at/
Also on: postgresql.org/message-id/ec1e6bb700f9eefceea0648656b38ab223c14c54.camel@cybertec.at
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: laurenz.albe@cybertec.at, david.g.johnston@gmail.com, tgl@sss.pgh.pa.us, petermittere@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: please define 'statement' in the glossary
In-Reply-To: <ec1e6bb700f9eefceea0648656b38ab223c14c54.camel@cybertec.at>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox