Date: Mon, 5 Mar 2018 13:44:39 +0900
From: Michael Paquier <michael@paquier.xyz>
To: Magnus Hagander <magnus@hagander.net>
Cc: Andres Freund <andres@anarazel.de>,
	Michael Paquier <michael.paquier@gmail.com>,
	Petr Jelinek <petr@2ndquadrant.com>,
	=?utf-8?B?xZ5haGFwIEHFn8OnxLE=?= <sahapasci@gmail.com>,
	pgsql-docs <pgsql-docs@postgresql.org>,
	Fujii Masao <masao.fujii@gmail.com>
Subject: Re: libpq options
Message-ID: <20180305044439.GA2266@paquier.xyz>
References: <20171122132714.1463.27247@wrigleys.postgresql.org>
 <CAB7nPqRZ-8BkUuF1UR+xzg3J+LDTcafbJ75DZGsfn+++iF5_aw@mail.gmail.com>
 <CAB7nPqTMQYKO4AJ6xfz-btAtvL-=CWxYnkXUOVEQGNk4Ey1k=Q@mail.gmail.com>
 <20180301093554.qrqgdnfwgs77tj23@alap3.anarazel.de>
 <20180302014938.GC1186@paquier.xyz>
 <CABUevEzwbfDb5fUWc7opVFyGBeCXqChrq-S1KXRSYDDexSuthw@mail.gmail.com>
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha512;
	protocol="application/pgp-signature"; boundary="mxv5cy4qt+RJ9ypb"
Content-Disposition: inline
In-Reply-To: 
 <CABUevEzwbfDb5fUWc7opVFyGBeCXqChrq-S1KXRSYDDexSuthw@mail.gmail.com>
Precedence: bulk


--mxv5cy4qt+RJ9ypb
Content-Type: multipart/mixed; boundary="wRRV7LY7NUeQGEoC"
Content-Disposition: inline


--wRRV7LY7NUeQGEoC
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

On Fri, Mar 02, 2018 at 12:58:50PM +0100, Magnus Hagander wrote:
> To nitpick:
>=20
> +       protocol. A Boolean value of <literal>true</literal> tells the
> backend
>=20
> We don't really have boolean values here, do we? It's just the string true
> that's treated as a boolean by the backend. It just sounds really weird to
> me when written that way. Particularly since the next sentence talks about
> passing "database" as the same thing.
>=20
> I know that's pretty much nitpicking, but I want to make sure I haven't
> actually missed/forgotten how some part of that one is handled..

Yes, that's indeed a bit inconsistent with the other parameters able to
use boolean-like parameters, like sslcompression or sslmode (deprecated
in favor requiressl), still those two ones are frontend-only
parameters, so they are just able to use "1" or "0".  Replication is
part of the startup packet which uses parse_bool() so valid values can
be true, false, yes, no, on, off, 1 or 0.  And it is even possible to
use upper-case characters.  So why not documenting all that precisely
then?

> It also talks separately about "going into walsender mode" (=3Dphysical
> replication) and "instructs the walsender to connect to the database". I
> think that's a bit confusing. I suggest just calling it "physical
> replication mode" and "logical replication mode", and not bother mentioni=
ng
> walsender since that's quite internal.

Indeed, this term is pretty spread across the documentation as well.

I have taken into account this feedback, and created the new version
attached, for a v2.

Thoughts?
--
Michael

--wRRV7LY7NUeQGEoC
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="replication-param-doc-v2.patch"
Content-Transfer-Encoding: quoted-printable

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2a8e1f2e07..8934559239 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1262,6 +1262,57 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       </listitem>
      </varlistentry>
=20
+     <varlistentry id=3D"libpq-connect-replication" xreflabel=3D"replicati=
on">
+      <term><literal>replication</literal></term>
+      <listitem>
+      <para>
+       This option determines if a backend should use the replication
+       protocol.  For a detailed description about the replication protoco=
l,
+       consult <xref linkend=3D"protocol-replication"/>. The following val=
ues,
+       which are case-insensitive, are supported:
+       <variablelist>
+        <varlistentry>
+         <term>
+          <literal>true</literal>, <literal>on</literal>,
+           <literal>yes</literal> or <literal>1</literal>
+         </term>
+         <listitem>
+          <para>
+           The backend goes into physical replication mode, wherein a small
+           set of replication commands can be issued instead of SQL statem=
ents.
+           Only the simple query protocol can be used in this case.
+          </para>
+         </listitem>
+        </varlistentry>
+
+        <varlistentry>
+         <term><literal>database</literal></term>
+         <listitem>
+          <para>
+           The backend goes into logical replication mode, as the value
+           instructs the backend to connect to the database specified in
+           the <literal>dbname</literal> parameter.  Only the simple query
+           protocol can be used in this case.
+          </para>
+         </listitem>
+        </varlistentry>
+
+        <varlistentry>
+         <term>
+          <literal>false</literal>, <literal>off</literal>,
+           <literal>no</literal> or <literal>0</literal>
+         </term>
+         <listitem>
+          <para>
+           The backend is a regular one, which is the default behavior.
+          </para>
+         </listitem>
+        </varlistentry>
+       </variablelist>
+      </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry id=3D"libpq-connect-sslmode" xreflabel=3D"sslmode">
       <term><literal>sslmode</literal></term>
       <listitem>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 3cec9e0b0c..2e231efac0 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1635,15 +1635,9 @@ that cannot support <literal>tls-unique</literal> fo=
r some reason.
=20
 <para>
 To initiate streaming replication, the frontend sends the
-<literal>replication</literal> parameter in the startup message. A Boolean=
 value
-of <literal>true</literal> tells the backend to go into walsender mode, wh=
erein a
-small set of replication commands can be issued instead of SQL statements.=
 Only
-the simple query protocol can be used in walsender mode.
-Replication commands are logged in the server log when
+<xref linkend=3D"libpq-connect-replication"/> connection parameter in the
+startup message. Replication commands are logged in the server log when
 <xref linkend=3D"guc-log-replication-commands"/> is enabled.
-Passing <literal>database</literal> as the value instructs walsender to co=
nnect to
-the database specified in the <literal>dbname</literal> parameter, which w=
ill allow
-the connection to be used for logical replication from that database.
 </para>
 <para>
  For the purpose of testing replication commands, you can make a replicati=
on

--wRRV7LY7NUeQGEoC--

--mxv5cy4qt+RJ9ypb
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQIzBAABCgAdFiEEG72nH6vTowiyblFKnvQgOdbyQH0FAlqcyzcACgkQnvQgOdby
QH25NA//eZd9iKDpQjNgBMxgzQ7Wx6Ilt8f+h7fCQ9MsT2HNTRKFbxT1w+64Yphr
uxGElNV4kuNZaM5REATcfFNC5G+BbMMiH1EoZ+qVuzpVUOVZzIKTqUD6fpWp1pwQ
A7hCo/MdI+pFp5W4WJ/XJk3ehBr/zuxEEXvKHmBTQBKn9UWLDbRs8unJjyu11DrL
6eaJ/8CjkJaXH0N4FzlvgXt1tq5V83w8frcKAGy/U48vOcWonzt/eLhdKf8lHje8
XdHL2mc1LJr7LIDCtf/3rguXjggyDWOZZ3iW5lbOQKAuVDcqkdzF/66vexNgo5eR
KPQOYvJVoelZHz3j6LDlFnXsqIM0hfEao3t42SOhMpn/FXL+OzMH6MsJ5LHFkZiC
NndT/xC9mkfIJLyT/cq6brU3oOy6FLjIlfDqnPrgqZWvu/9uGJgt5Br5m1bJhJQK
0STmbKECf4gS0d5Sqd2myrUsxKaKUkpgFfaXaGO3+03uSFPSYk0uLfYIc7RsO/VY
DeXpIoHC8ZWXvsonotkjFoPVpGkyhkCbAHskUe7v2DNwFWmH4CHRus07EuN83uZb
GdEOZxoi9TiI6ZBsrXxhkZi2ABZTt9ahHF2b9JIwmZ/zpHL1uyUx/CZxut33scyT
P1TueJ16DZL6bbl+Ce5aRRU+t5GrmEuNDDWTu5qDwyHnrJfG0ps=
=dK1s
-----END PGP SIGNATURE-----

--mxv5cy4qt+RJ9ypb--