From 0c2c81b403db420bfce36f168887db72932dbf09 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Tue, 6 Mar 2018 21:00:10 -0500
Subject: [PATCH] doc: Add replication parameter to libpq documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

Author: Michael Paquier <michael@paquier.xyz>
Reported-by: Şahap Aşçı <sahapasci@gmail.com>
Reviewed-by: Vik Fearing <vik.fearing@2ndquadrant.com>
---
 doc/src/sgml/libpq.sgml    | 58 ++++++++++++++++++++++++++++++++++++++
 doc/src/sgml/protocol.sgml | 36 ++++++++++++++++-------
 2 files changed, 84 insertions(+), 10 deletions(-)

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 2a8e1f2e07..da9421486b 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1262,6 +1262,64 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       </listitem>
      </varlistentry>
 
+     <varlistentry id="libpq-connect-replication" xreflabel="replication">
+      <term><literal>replication</literal></term>
+      <listitem>
+      <para>
+       This option determines whether the connection should use the
+       replication protocol instead of the normal protocol.  This is what
+       PostgreSQL replication connections as well as tools such as
+       <application>pg_basebackup</application> use internally, but it can
+       also be used by third-party applications.  For a description of the
+       replication protocol, consult <xref linkend="protocol-replication"/>.
+      </para>
+
+      <para>
+       The following values, which are case-insensitive, are supported:
+       <variablelist>
+        <varlistentry>
+         <term>
+          <literal>true</literal>, <literal>on</literal>,
+          <literal>yes</literal>, <literal>1</literal>
+         </term>
+         <listitem>
+          <para>
+           The connection goes into physical replication mode.
+          </para>
+         </listitem>
+        </varlistentry>
+
+        <varlistentry>
+         <term><literal>database</literal></term>
+         <listitem>
+          <para>
+           The connection goes into logical replication mode, connecting to
+           the database specified in the <literal>dbname</literal> parameter.
+          </para>
+         </listitem>
+        </varlistentry>
+
+        <varlistentry>
+         <term>
+          <literal>false</literal>, <literal>off</literal>,
+          <literal>no</literal>, <literal>0</literal>
+         </term>
+         <listitem>
+          <para>
+           The connection is a regular one, which is the default behavior.
+          </para>
+         </listitem>
+        </varlistentry>
+       </variablelist>
+      </para>
+
+      <para>
+       In physical or logical replication mode, only the simple query protocol
+       can be used.
+      </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..4fd61d7c2d 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1635,16 +1635,27 @@ 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="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.
+<literal>replication</literal> parameter in the startup message. A Boolean
+value of <literal>true</literal> (or <literal>on</literal>,
+<literal>yes</literal>, <literal>1</literal>) tells the backend to go into
+physical replication walsender mode, wherein a small set of replication
+commands, shown below, can be issued instead of SQL statements.
+</para>
+
+<para>
+Passing <literal>database</literal> as the value for the
+<literal>replication</literal> parameter instructs the backend to go into
+logical replication walsender mode, connecting to the database specified in
+the <literal>dbname</literal> parameter.  In logical replication walsender
+mode, the replication commands shown below as well as normal SQL commands can
+be issued.
+</para>
+
+<para>
+In either physical replication or logical replication walsender mode, only the
+simple query protocol can be used.
 </para>
+
 <para>
  For the purpose of testing replication commands, you can make a replication
  connection via <application>psql</application> or any other <literal>libpq</literal>-using
@@ -1659,7 +1670,12 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
 </para>
 
 <para>
-The commands accepted in walsender mode are:
+Replication commands are logged in the server log when
+<xref linkend="guc-log-replication-commands"/> is enabled.
+</para>
+
+<para>
+The commands accepted in replication mode are:
 <variablelist>
   <varlistentry>
     <term><literal>IDENTIFY_SYSTEM</literal>
-- 
2.40.0