Re: pgbench doc fix

>>>>> So I do not think a more precise wording harms. Maybe: "prepared: use
>>>>> extended query protocol with REUSED named prepared statements" would
>>>>> be even less slightly ambiguous.
>>>>
>>>> I like this. But maybe we can remove "named"?
>>>
>>> I also think it makes sense to adjust wording a bit here, and this
>>> version
>>> sounds good (taking into account the commentary about "named"). I'm
>>> moving this
>>> to the next CF, where the question would be if anyone from commiters
>>> can agree
>>> with this point.
>>
>> I don't see a concrete proposed patch here after the discussion.
>>
>> Reading the documentation again, we could go for much more detail
>> here.
>> For example, what's the point of having -M simple vs -M extended?
> 
> They do not use the same libpq-level approach (PQsendQuery vs
> PQsendQueryParams), so they are not exercising the same type of
> client? Pgbench is also about testing libpq performance.

Yes, -M extended is pretty slow because for each query it needs to
send parse/bind/describe/execute messages.  -M prepared is much faster
because for the second and subsequent iterations of query, it does not
need to execute parse analysis, which means not only less message are
exchanged but parse analysis are omitted for the second and subsequent
query iterations.

Here are quick test results using pgbench -S -M $mode -c 10 -T 30,
where $mode is "simple", "extended" or "prepared" on my Ubuntu 18
laptop. The TPS numbers are average on each 3 trials for "execuding
connections establishing".

simpe:
48804.8383 TPS

extended:
39735.4278 TPS

prepared:
83459.2293 TPS

So "prepared" is roughly 2x faster than "extended".

Based on this, I would suggest to modify exiting descriptions in
pgbench doc regarding "-M querymode":

From:
-------------------------------------------------------------------
-M querymode
--protocol=querymode

    Protocol to use for submitting queries to the server:

        simple: use simple query protocol.

        extended: use extended query protocol.

        prepared: use extended query protocol with prepared statements.
-------------------------------------------------------------------

To:
-------------------------------------------------------------------
-M querymode
--protocol=querymode

    Protocol to use for submitting queries to the server:

        simple: use simple query protocol.

        extended: use extended query protocol.

        prepared: use extended query protocol with prepared statements.

    Because in "prepared" mode pgbench reuses the parse analysis
    result for the second and subsequent query iteration, pgbench runs
    faster in the prepared mode than in other modes.
-------------------------------------------------------------------

Best regards,
--
Tatsuo Ishii
SRA OSS, Inc. Japan
English: http://www.sraoss.co.jp/index_en.php
Japanese:http://www.sraoss.co.jp
diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml
index b5e3a62a33..c2a2ff9707 100644
--- a/doc/src/sgml/ref/pgbench.sgml
+++ b/doc/src/sgml/ref/pgbench.sgml
@@ -473,6 +473,13 @@ pgbench <optional> <replaceable>options</replaceable> </optional> <replaceable>d
             <para><literal>prepared</literal>: use extended query protocol with prepared statements.</para>
            </listitem>
           </itemizedlist>
+
+        Because in "prepared" mode <application>pgbench</application> reuses
+        the parse analysis result for the second and subsequent query
+        iteration, <application>pgbench</application> runs faster in the
+        prepared mode than in other modes.
+       </para>
+       <para>
         The default is simple query protocol.  (See <xref linkend="protocol"/>
         for more information.)
        </para>