Doc: Generated column replication.

Commit 7054186c4e added the support to publish generated stored columns.
This patch adds detailed documentation for that feature.

Author: Peter Smith 
Reviewed-by: Vignesh C 
Reviewed-by: Peter Eisentraut 
Reviewed-by: Amit Kapila 
Discussion: https://postgr.es/m/B80D17B2-2C8E-4C7D-87F2-E5B4BE3C069E%40gmail.com
Discussion: https://postgr.es/m/CAHut+PsYmAvKhUjA1AaR1rxLdeSBKiBko8wKyf4_H8nEEqDuOg@mail.gmail.com

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index dea04d64db66b6b0b58a2d1066409b2932d4a776..7ff39ae8c67dd085ad896e269132fcb40f63cf61 100644 (file)
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -519,6 +519,7 @@ CREATE TABLE people (
       
       publish_generated_columns or by including them
       in the column list of the CREATE PUBLICATION command.
+      See  for details.
      
     
    

diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 07a07dfe0ba936527bcf2b896daba81d0fe25d4e..613abcd28b7ddee8da7549b63dcabb034ffba03c 100644 (file)
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -1429,6 +1429,14 @@ test_sub=# SELECT * FROM child ORDER BY a;
    of columns in the list is not preserved.
   
 
+  
+   Generated columns can also be specified in a column list. This allows
+   generated columns to be published, regardless of the publication parameter
+   
+   publish_generated_columns. See
+    for details.
+  
+
   
    Specifying a column list when the publication also publishes
    FOR TABLES IN SCHEMA
@@ -1594,6 +1602,190 @@ test_sub=# SELECT * FROM t1 ORDER BY id;
 
  
 
+ 
+  Generated Column Replication
+
+  
+   Typically, a table at the subscriber will be defined the same as the
+   publisher table, so if the publisher table has a 
+   GENERATED column then the subscriber table will
+   have a matching generated column. In this case, it is always the subscriber
+   table generated column value that is used.
+  
+
+  
+   For example, note below that subscriber table generated column value comes from the
+   subscriber column's calculation.
+
+test_pub=# CREATE TABLE tab_gen_to_gen (a int, b int GENERATED ALWAYS AS (a + 1) STORED);
+CREATE TABLE
+test_pub=# INSERT INTO tab_gen_to_gen VALUES (1),(2),(3);
+INSERT 0 3
+test_pub=# CREATE PUBLICATION pub1 FOR TABLE tab_gen_to_gen;
+CREATE PUBLICATION
+test_pub=# SELECT * FROM tab_gen_to_gen;
+ a | b
+---+---
+ 1 | 2
+ 2 | 3
+ 3 | 4
+(3 rows)
+
+test_sub=# CREATE TABLE tab_gen_to_gen (a int, b int GENERATED ALWAYS AS (a * 100) STORED);
+CREATE TABLE
+test_sub=# CREATE SUBSCRIPTION sub1 CONNECTION 'dbname=test_pub' PUBLICATION pub1;
+CREATE SUBSCRIPTION
+test_sub=# SELECT * from tab_gen_to_gen;
+ a | b
+---+----
+ 1 | 100
+ 2 | 200
+ 3 | 300
+(3 rows)
+
+  
+
+  
+   In fact, prior to version 18.0, logical replication does not publish
+   GENERATED columns at all.
+  
+
+  
+   But, replicating a generated column to a regular column can sometimes be
+   desirable.
+   
+    
+     This feature may be useful when replicating data to a
+     non-PostgreSQL database via output plugin, especially if the target database
+     does not support generated columns.
+    
+  
+  
+
+  
+   Generated columns are not published by default, but users can opt to
+   publish stored generated columns just like regular ones.
+  
+
+  
+   There are two ways to do this:
+   
+     
+      
+       Set the PUBLICATION parameter
+       
+       publish_generated_columns to stored.
+       This instructs PostgreSQL logical replication to publish current and
+       future stored generated columns of the publication's tables.
+      
+     
+
+     
+      
+       Specify a table column list
+       to explicitly nominate which stored generated columns will be published.
+      
+
+      
+       
+        When determining which table columns will be published, a column list
+        takes precedence, overriding the effect of the
+        publish_generated_columns parameter.
+       
+      
+     
+   
+  
+
+  
+   The following table summarizes behavior when there are generated columns
+   involved in the logical replication. Results are shown for when
+   publishing generated columns is not enabled, and for when it is
+   enabled.
+  
+
+  
+   Replication Result Summary
+   
+
+    
+     
+      Publish generated columns?
+      Publisher table column
+      Subscriber table column
+      Result
+     
+    
+
+    
+     
+      No
+      GENERATED
+      GENERATED
+      Publisher table column is not replicated. Use the subscriber table generated column value.
+     
+
+     
+      No
+      GENERATED
+      regular
+      Publisher table column is not replicated. Use the subscriber table regular column default value.
+     
+
+     
+      No
+      GENERATED
+      --missing--
+      Publisher table column is not replicated. Nothing happens.
+     
+
+     
+      Yes
+      GENERATED
+      GENERATED
+      ERROR. Not supported.
+     
+
+     
+      Yes
+      GENERATED
+      regular
+      Publisher table column value is replicated to the subscriber table column.
+     
+
+     
+      Yes
+      GENERATED
+      --missing--
+      ERROR. The column is reported as missing from the subscriber table.
+     
+    
+   
+  
+
+  
+   
+    There's currently no support for subscriptions comprising several
+    publications where the same table has been published with different column
+    lists. See .
+   
+
+   
+    This same situation can occur if one publication is publishing generated
+    columns, while another publication in the same subscription is not
+    publishing generated columns for the same table.
+   
+  
+
+  
+   
+    If the subscriber is from a release prior to 18, then initial table
+    synchronization won't copy generated columns even if they are defined in
+    the publisher.
+   
+  
+ 
+
  
   Conflicts
 

diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index e822ea2aaa9a3dfe4ae5b0d2e1dcb466965b1df7..73f0c8d89fb00c1af3db28b90705b48ebcc7b232 100644 (file)
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -217,6 +217,11 @@ CREATE PUBLICATION name
            in the publisher.
           
          
+
+         
+          See  for more details about
+          logical replication of generated columns.
+