v4-0001-doc-Update-information-of-new-messages-for-logica.patch

From 502c87886770205cc39d72d1e0ed9eb220e5ff21 Mon Sep 17 00:00:00 2001
From: Ajin Cherian <ajinc@fast.au.fujitsu.com>
Date: Thu, 8 Apr 2021 22:44:50 -0400
Subject: [PATCH v4] doc: Update information of new messages for logical
 replication.

Updated documentation for new messages added for streaming in-progress
transactions, as well as changes made to the existing messages. It also
updates the information of protocol versions supported for logical
replication.

Author: Ajin Cherian
Reviewed-by: Amit Kapila, Peter Smith
Discussion: https://postgr.es/m/CAFPTHDYHN9m=MZZct-B=BYg_TETvv+kXvL9RD2DpaBS5pGxGYg@mail.gmail.com
---
 doc/src/sgml/protocol.sgml | 298 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 292 insertions(+), 6 deletions(-)

diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 380be5f..bf7d737 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -2797,9 +2797,11 @@ The commands accepted in replication mode are:
      </term>
      <listitem>
       <para>
-       Protocol version. Currently only version <literal>1</literal> is
-       supported.
-      </para>
+       Protocol version. Currently versions <literal>1</literal> and
+       <literal>2</literal> are supported. The version <literal>2</literal>
+       is supported only for server versions 14 and above, and is used to allow
+       streaming of large in-progress transactions.
+     </para>
      </listitem>
     </varlistentry>
 
@@ -2855,7 +2857,10 @@ The commands accepted in replication mode are:
   <para>
    The logical replication protocol sends individual transactions one by one.
    This means that all messages between a pair of Begin and Commit messages
-   belong to the same transaction.
+   belong to the same transaction. It also sends changes of large in-progress
+   transactions between a pair of Stream Start and Stream Stop messages. The
+   last stream of such a transaction contains Stream Commit or Stream Abort
+   message.
   </para>
 
   <para>
@@ -6457,8 +6462,10 @@ Message
 </term>
 <listitem>
 <para>
-                Xid of the transaction. The XID is sent only when user has
-                requested streaming of in-progress transactions.
+               Since protocol version 2
+</para>
+<para>
+                Xid of the transaction (only present for streamed transactions).
 </para>
 </listitem>
 </varlistentry>
@@ -6647,6 +6654,19 @@ Relation
 </term>
 <listitem>
 <para>
+              Since protocol version 2
+</para>
+<para>
+               Xid of the transaction (only present for streamed transactions).
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int32
+</term>
+<listitem>
+<para>
                 ID of the relation.
 </para>
 </listitem>
@@ -6768,6 +6788,19 @@ Type
 </term>
 <listitem>
 <para>
+              Since protocol version 2
+</para>
+<para>
+               Xid of the transaction (only present for streamed transactions).
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int32
+</term>
+<listitem>
+<para>
                 ID of the data type.
 </para>
 </listitem>
@@ -6822,6 +6855,19 @@ Insert
 </term>
 <listitem>
 <para>
+               Since protocol version 2
+</para>
+<para>
+                Xid of the transaction (only present for streamed transactions).
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int32
+</term>
+<listitem>
+<para>
                 ID of the relation corresponding to the ID in the relation
                 message.
 </para>
@@ -6878,6 +6924,19 @@ Update
 </term>
 <listitem>
 <para>
+              Since protocol version 2
+</para>
+<para>
+               Xid of the transaction (only present for streamed transactions).
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int32
+</term>
+<listitem>
+<para>
                 ID of the relation corresponding to the ID in the relation
                 message.
 </para>
@@ -6981,6 +7040,19 @@ Delete
 </term>
 <listitem>
 <para>
+              Since protocol version 2
+</para>
+<para>
+               Xid of the transaction (only present for streamed transactions).
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int32
+</term>
+<listitem>
+<para>
                 ID of the relation corresponding to the ID in the relation
                 message.
 </para>
@@ -7059,6 +7131,19 @@ Truncate
 </term>
 <listitem>
 <para>
+              Since protocol version 2
+</para>
+<para>
+               Xid of the transaction (only present for streamed transactions).
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int32
+</term>
+<listitem>
+<para>
                 Number of relations
 </para>
 </listitem>
@@ -7091,6 +7176,207 @@ Truncate
 </listitem>
 </varlistentry>
 
+<varlistentry>
+<term>
+Stream Start
+</term>
+<listitem>
+<para>
+
+<variablelist>
+<varlistentry>
+<term>
+        Byte1('S')
+</term>
+<listitem>
+<para>
+               Since protocol version 2
+</para>
+<para>
+                Identifies the message as a stream start message.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int32
+</term>
+<listitem>
+<para>
+                Xid of the transaction.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int8
+</term>
+<listitem>
+<para>
+                A value of 1 indicates this is the first stream segment for
+                this XID, 0 for any other stream segment.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+Stream Stop
+</term>
+<listitem>
+<para>
+
+<variablelist>
+<varlistentry>
+<term>
+        Byte1('E')
+</term>
+<listitem>
+<para>
+               Since protocol version 2
+</para>
+<para>
+                Identifies the message as a stream stop message.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+Stream Commit
+</term>
+<listitem>
+<para>
+
+<variablelist>
+<varlistentry>
+<term>
+        Byte1('c')
+</term>
+<listitem>
+<para>
+               Since protocol version 2
+</para>
+<para>
+                Identifies the message as a stream commit message.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int32
+</term>
+<listitem>
+<para>
+                Xid of the transaction.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int8
+</term>
+<listitem>
+<para>
+                Flags; currently unused (must be 0).
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int64
+</term>
+<listitem>
+<para>
+                The LSN of the commit.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int64
+</term>
+<listitem>
+<para>
+                The end LSN of the transaction.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int64
+</term>
+<listitem>
+<para>
+                Commit timestamp of the transaction. The value is in number
+                of microseconds since PostgreSQL epoch (2000-01-01).
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+Stream Abort
+</term>
+<listitem>
+<para>
+
+<variablelist>
+<varlistentry>
+<term>
+        Byte1('A')
+</term>
+<listitem>
+<para>
+               Since protocol version 2
+</para>
+<para>
+                Identifies the message as a stream abort message.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int32
+</term>
+<listitem>
+<para>
+                Xid of the transaction.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int32
+</term>
+<listitem>
+<para>
+                Xid of the subtransaction (will be same as xid of the transaction for top-level
+                transactions).
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</para>
+</listitem>
+</varlistentry>
+
 </variablelist>
 
 <para>
-- 
1.8.3.1