From ecb696527c01908d54b7a7aa2bd9179585b46459 Mon Sep 17 00:00:00 2001
From: Amit Kapila
Date: Thu, 23 Mar 2023 08:45:51 +0530
Subject: Allow logical replication to copy tables in binary format.

This patch allows copying tables in the binary format during table
synchronization when the binary option for a subscription is enabled.
Previously, tables are copied in text format even if the subscription is
created with the binary option enabled. Copying tables in binary format
may reduce the time spent depending on column types.

A binary copy for initial table synchronization is supported only when
both publisher and subscriber are v16 or later.

Author: Melih Mutlu
Reviewed-by: Peter Smith, Shi yu, Euler Taveira, Vignesh C,  Kuroda Hayato, Osumi Takamichi, Bharath Rupireddy, Hou Zhijie
Discussion: https://postgr.es/m/CAGPVpCQvAziCLknEnygY0v1-KBtg%2BOm-9JHJYZOnNPKFJPompw%40mail.gmail.com
---
 doc/src/sgml/logical-replication.sgml     |  4 +++-
 doc/src/sgml/ref/alter_subscription.sgml  |  5 +++++
 doc/src/sgml/ref/create_subscription.sgml | 28 ++++++++++++++++++++++------
 3 files changed, 30 insertions(+), 7 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 6b0e300adc0..3836d13ad3d 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -251,7 +251,9 @@
    column of type <type>bigint</type>.  The target table can also have
    additional columns not provided by the published table.  Any such columns
    will be filled with the default value as specified in the definition of the
-   target table.
+   target table. However, logical replication in binary format is more
+   restrictive. See the <link linkend="sql-createsubscription-binary"><literal>binary</literal>
+   option</link> of <command>CREATE SUBSCRIPTION</command> for details.
   </para>
 
   <sect2 id="logical-replication-subscription-slot">
diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml
index 964fcbb8ff7..e92346edeff 100644
--- a/doc/src/sgml/ref/alter_subscription.sgml
+++ b/doc/src/sgml/ref/alter_subscription.sgml
@@ -177,6 +177,11 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
           how <literal>copy_data = true</literal> can interact with the
           <literal>origin</literal> parameter.
          </para>
+         <para>
+          See the <link linkend="sql-createsubscription-binary"><literal>binary</literal>
+          option</link> of <command>CREATE SUBSCRIPTION</command> for details
+          about copying pre-existing data in binary format.
+         </para>
         </listitem>
        </varlistentry>
       </variablelist></para>
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 51c45f17c7d..9d4b9d4e338 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -185,15 +185,25 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
 
       <variablelist>
 
-       <varlistentry>
+       <varlistentry id="sql-createsubscription-binary" xreflabel="binary">
         <term><literal>binary</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
-          Specifies whether the subscription will request the publisher to
-          send the data in binary format (as opposed to text).
-          The default is <literal>false</literal>.
-          Even when this option is enabled, only data types having
-          binary send and receive functions will be transferred in binary.
+          Specifies whether the subscription will request the publisher to send
+          the data in binary format (as opposed to text). The default is
+          <literal>false</literal>. Any initial table synchronization copy
+          (see <literal>copy_data</literal>) also uses the same format. Binary
+          format can be faster than the text format, but it is less portable
+          across machine architectures and <productname>PostgreSQL</productname>
+          versions. Binary format is very data type specific; for example, it
+          will not allow copying from a <type>smallint</type> column to an
+          <type>integer</type> column, even though that would work fine in text
+          format. Even when this option is enabled, only data types having binary
+          send and receive functions will be transferred in binary. Note that
+          the initial synchronization requires all data types to have binary
+          send and receive functions, otherwise the synchronization will fail
+          (see <xref linkend="sql-createtype"/> for more about send/receive
+          functions).
          </para>
 
          <para>
@@ -203,6 +213,12 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
           such a case, data transfer will fail, and
           the <literal>binary</literal> option cannot be used.
          </para>
+
+         <para>
+          If the publisher is a <productname>PostgreSQL</productname> version
+          before 16, then any initial table synchronization will use text format
+          even if <literal>binary = true</literal>.
+         </para>
         </listitem>
        </varlistentry>
 
-- 
cgit v1.2.3