On Sun, 06 Nov 2022 12:54:17 -0500
Tom Lane <[email protected]> wrote:
> Yugo NAGATA <[email protected]> writes:
> >> The attached patch tries to add comments explaining it on the functions.
>
> > I forward it to the hackers list because the patch is to fix comments.
>
> What do you think of the attached wording?
It looks good to me. That describes the expected behaviour exactly.
> I don't think the pipeline angle is of concern to anyone who might be
> reading these comments with the aim of understanding what guarantees
> they have. Perhaps there should be more about that in the user-facing
> docs, though.
I agree with that we don't need to mention pipelining in these comments,
and that we need more in the documentation. I attached a doc patch to add
a mention of commands that do internal commit to the pipelining section.
Also, this adds a reference for the pipelining protocol to the libpq doc.
Regards,
Yugo Nagata
--
Yugo NAGATA <[email protected]>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 3c9bd3d673..727a024e60 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -5058,7 +5058,8 @@ int PQflush(PGconn *conn);
While the pipeline API was introduced in
<productname>PostgreSQL</productname> 14, it is a client-side feature
which doesn't require special server support and works on any server
- that supports the v3 extended query protocol.
+ that supports the v3 extended query protocol; see <xref linkend="protocol-flow-pipelining"/>.
+
</para>
<sect2 id="libpq-pipeline-using">
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 5fdd429e05..2edd42d7e9 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1095,6 +1095,9 @@ SELCT 1/0;<!-- this typo is intentional -->
that cannot be executed inside a transaction block. If one of
these is executed in a pipeline, it will, upon success, force an
immediate commit to preserve database consistency.
+ In addition, execution one of some commands (such as
+ <command>VACUUM ANALYZE</command>) that start/commit transactions
+ internally also can cause an immediate commit even if it fails.
A Sync immediately following one of these has no effect except to
respond with ReadyForQuery.
</para>
