From: Etsuro Fujita <efujita@postgresql.org>
Date: Fri, 26 Apr 2019 09:10:06 +0000 (+0900)
Subject: Add FDW documentation notes about insert and update tuple routing and COPY.
X-Git-Tag: REL_11_3~26
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=53f48a2abb7b13a866d62e68e6ecfb11b637b0b1;p=thirdparty%2Fpostgresql.git

Add FDW documentation notes about insert and update tuple routing and COPY.

Author: Laurenz Albe and Etsuro Fujita
Reviewed-by: Laurenz Albe and Amit Langote
Backpatch-through: 11 where support for that by FDWs was added
Discussion: https://postgr.es/m/bf36a0288e8f31b4f2f40952e225bf892dc1ffc5.camel@cybertec.at
---

diff --git a/doc/src/sgml/fdwhandler.sgml b/doc/src/sgml/fdwhandler.sgml
index 7b758bdf09b..f719b06664b 100644
--- a/doc/src/sgml/fdwhandler.sgml
+++ b/doc/src/sgml/fdwhandler.sgml
@@ -587,6 +587,14 @@ ExecForeignInsert(EState *estate,
      with an error message.
     </para>
 
+    <para>
+     Note that this function is also called when inserting routed tuples into
+     a foreign-table partition or executing <command>COPY FROM</command> on
+     a foreign table, in which case it is called in a different way than it
+     is in the <command>INSERT</command> case.  See the callback functions
+     described below that allow the FDW to support that.
+    </para>
+
     <para>
 <programlisting>
 TupleTableSlot *
@@ -743,6 +751,13 @@ BeginForeignInsert(ModifyTableState *mtstate,
      <literal>NULL</literal>, no action is taken for the initialization.
     </para>
 
+    <para>
+     Note that if the FDW does not support routable foreign-table partitions
+     and/or executing <command>COPY FROM</command> on foreign tables, this
+     function or <function>ExecForeignInsert</function> subsequently called
+     must throw error as needed.
+    </para>
+
     <para>
 <programlisting>
 void
diff --git a/doc/src/sgml/release-11.sgml b/doc/src/sgml/release-11.sgml
index 14e2726f0c1..5c9f41a17aa 100644
--- a/doc/src/sgml/release-11.sgml
+++ b/doc/src/sgml/release-11.sgml
@@ -2594,6 +2594,9 @@ Branch: REL9_3_STABLE [84261eb10] 2018-10-19 17:02:26 -0400
        <para>
         This is supported by <filename>postgres_fdw</filename>
         foreign tables.
+        Since the <function>ExecForeignInsert</function> callback function
+        is called for this in a different way than it used to be,
+        foreign data wrappers must be modified to cope with this change.
        </para>
       </listitem>