Fix documentation on partitioning vs. foreign tables

1. The PARTITION OF clause of CREATE FOREIGN TABLE was not explained in
   the CREATE FOREIGN TABLE reference page.  Add it.
   (Postgres 10 onwards)

2. The limitation that tuple routing cannot target partitions that are
   foreign tables was not documented clearly enough.  Improve wording.
   (Postgres 10 onwards)

3. The UPDATE tuple re-routing concurrency behavior was explained in
   the DDL chapter, which doesn't seem the right place.  Move it to the
   UPDATE reference page instead.  (Postgres 11 onwards).

Authors: Amit Langote, David Rowley.
Reviewed-by: Etsuro Fujita.
Reported-by: Derek Hans
Discussion: https://postgr.es/m/CAGrP7a3Xc1Qy_B2WJcgAD8uQTS_NDcJn06O5mtS_Ne1nYhBsyw@mail.gmail.com

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 4c1d2f607bbab8b9048d4416cb73f38714f95cf5..110f6b46570e03ff1b090e40cb15306422b191ca 100644 (file)
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3856,27 +3856,6 @@ ALTER TABLE measurement ATTACH PARTITION measurement_y2008m02
       
      
 
-     
-      
-       When an UPDATE causes a row to move from one
-       partition to another, there is a chance that another concurrent
-       UPDATE or DELETE will get a
-       serialization failure error.  Suppose session 1 is performing an
-       UPDATE on a partition key, and meanwhile a concurrent
-       session 2 for which this row is visible performs an
-       UPDATE or DELETE operation on this
-       row.  In such case, session 2's UPDATE or
-       DELETE, will detect the row movement and raise a
-       serialization failure error (which always returns with an SQLSTATE code
-       '40001').  Applications may wish to retry the transaction if this
-       occurs.  In the usual case where the table is not partitioned, or where
-       there is no row movement, session 2 would have identified the newly
-       updated row and carried out the
-       UPDATE/DELETE on this new row
-       version.
-      
-     
-
      
       
        BEFORE ROW triggers, if necessary, must be defined

diff --git a/doc/src/sgml/ref/create_foreign_table.sgml b/doc/src/sgml/ref/create_foreign_table.sgml
index 37a45b26dbcebd95580fde075bb74a6824054944..19eb5341e7da94b1c0bb10d8ee7e189fe1cb6fd6 100644 (file)
--- a/doc/src/sgml/ref/create_foreign_table.sgml
+++ b/doc/src/sgml/ref/create_foreign_table.sgml
@@ -160,6 +160,18 @@ CHECK ( expression ) [ NO INHERIT ]
     
    
 
+   
+    PARTITION OF parent_table FOR VALUES partition_bound_spec
+    
+     
+      This form can be used to create the foreign table as partition of
+      the given parent table with specified partition bound values.
+      See the similar form of
+       for more details.
+     
+    
+   
+
    
     CONSTRAINT constraint_name
     
@@ -308,6 +320,12 @@ CHECK ( expression ) [ NO INHERIT ]
     responsibility to ensure that the constraint definition matches
     reality.
    
+
+   
+    While rows can be moved from local partitions to a foreign-table partition
+    (provided the foreign data wrapper supports tuple routing), they cannot be
+    moved from a foreign-table partition to another partition.
+   
  
 
  

diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml
index 77430a586cbe60567cc08fb52eb866c76ff0e74a..f58dcd8877be28551ea75382c5a3047af175c8b8 100644 (file)
--- a/doc/src/sgml/ref/update.sgml
+++ b/doc/src/sgml/ref/update.sgml
@@ -287,13 +287,30 @@ UPDATE count
    row satisfies its partition constraint, then the row is moved to that
    partition. If there is no such partition, an error will occur.  Behind the
    scenes, the row movement is actually a DELETE and
-   INSERT operation. However, there is a possibility that a
-   concurrent UPDATE or DELETE on the
-   same row may miss this row. For details see the section
-   .
-   Currently, rows cannot be moved from a partition that is a
-   foreign table to some other partition, but they can be moved into a foreign
-   table if the foreign data wrapper supports it.
+   INSERT operation.
+  
+
+  
+   There is a possibility that a concurrent UPDATE or
+   DELETE on the row being moved will get a serialization
+   failure error.  Suppose session 1 is performing an UPDATE
+   on a partition key, and meanwhile a concurrent session 2 for which this
+   row is visible performs an UPDATE or
+   DELETE operation on this row.  In such case,
+   session 2's UPDATE or DELETE will
+   detect the row movement and raise a serialization failure error (which
+   always returns with an SQLSTATE code '40001').  Applications may wish to
+   retry the transaction if this occurs.  In the usual case where the table
+   is not partitioned, or where there is no row movement, session 2 would
+   have identified the newly updated row and carried out the
+   UPDATE/DELETE on this new row
+    version.
+  
+
+  
+   Note that while rows can be moved from local partitions to a foreign-table
+   partition (provided the foreign data wrapper supports tuple routing), they
+   cannot be moved from a foreign-table partition to another partition.