Doc: be clearer that foreign-table partitions need user-added constraints.

A very well-informed user might deduce this from what we said already,
but I'd bet against it.  Lay it out explicitly.

While here, rewrite the comment about tuple routing to be more
intelligible to an average SQL user.

Per bug #17395 from Alexander Lakhin.  Back-patch to v11.  (The text
in this area is different in v10 and I'm not sufficiently excited
about this point to adapt the patch.)

Discussion: https://postgr.es/m/17395-8c326292078d1a57@postgresql.org

2 files changed, 29 insertions, 10 deletions

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index e36a9b1e2e..364382ac93 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3713,9 +3713,12 @@ VALUES ('Albany', NULL, NULL, 'NY');
    </para>
 
    <para>
-    Partitions can also be foreign tables, although they have some limitations
-    that normal tables do not; see <xref linkend="sql-createforeigntable"/> for
-    more information.
+    Partitions can also be <link linkend="ddl-foreign-data">foreign
+    tables</link>, although considerable care is needed because it is then
+    the user's responsibility that the contents of the foreign table
+    satisfy the partitioning rule.  There are some other restrictions as
+    well.  See <xref linkend="sql-createforeigntable"/> for more
+    information.
    </para>
 
    <sect3 id="ddl-partitioning-declarative-example">
diff --git a/doc/src/sgml/ref/create_foreign_table.sgml b/doc/src/sgml/ref/create_foreign_table.sgml
index e97b3d8963..d83f5b6db9 100644
--- a/doc/src/sgml/ref/create_foreign_table.sgml
+++ b/doc/src/sgml/ref/create_foreign_table.sgml
@@ -348,11 +348,33 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ]
     constraints on foreign tables, it does assume that they are correct
     for purposes of query optimization.  If there are rows visible in the
     foreign table that do not satisfy a declared constraint, queries on
-    the table might produce incorrect answers.  It is the user's
+    the table might produce errors or incorrect answers.  It is the user's
     responsibility to ensure that the constraint definition matches
     reality.
    </para>
 
+   <caution>
+    <para>
+     When a foreign table is used as a partition of a partitioned table,
+     there is an implicit constraint that its contents must satisfy the
+     partitioning rule.  Again, it is the user's responsibility to ensure
+     that that is true, which is best done by installing a matching
+     constraint on the remote server.
+    </para>
+   </caution>
+
+   <para>
+    Within a partitioned table containing foreign-table partitions,
+    an <command>UPDATE</command> that changes the partition key value can
+    cause a row to be moved from a local partition to a foreign-table
+    partition, provided the foreign data wrapper supports tuple routing.
+    However it is not currently possible to move a row from a
+    foreign-table partition to another partition.
+    An <command>UPDATE</command> that would require doing that will fail
+    due to the partitioning constraint, assuming that that is properly
+    enforced by the remote server.
+   </para>
+
    <para>
     Similar considerations apply to generated columns.  Stored generated
     columns are computed on insert or update on the local
@@ -362,12 +384,6 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ]
     generated columns that are consistent with the generation expression.
     Again, this might result in incorrect query results.
    </para>
-
-   <para>
-    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.
-   </para>
  </refsect1>
 
  <refsect1 id="sql-createforeigntable-examples">