On Fri, Mar 02, 2018 at 12:58:50PM +0100, Magnus Hagander wrote: > To nitpick: > > + protocol. A Boolean value of <literal>true</literal> tells the > backend > > 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. > > 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" (=physical > 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 mentioning > 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
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>
+ <varlistentry id="libpq-connect-replication" xreflabel="replication">
+ <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 protocol,
+ consult <xref linkend="protocol-replication"/>. The following values,
+ 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 statements.
+ 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="libpq-connect-sslmode" xreflabel="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> for some reason.
<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, wherein 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="libpq-connect-replication"/> connection parameter in the
+startup message. Replication commands are logged in the server log when
<xref linkend="guc-log-replication-commands"/> is enabled.
-Passing <literal>database</literal> as the value instructs walsender to connect to
-the database specified in the <literal>dbname</literal> parameter, which will 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 replication
signature.asc
Description: PGP signature
