From 3d956d9562aa4811b5eaaaf5314d361c61be2ae0 Mon Sep 17 00:00:00 2001
From: Robert Haas <rhaas@postgresql.org>
Date: Fri, 6 Apr 2018 19:16:11 -0400
Subject: Allow insert and update tuple routing and COPY for foreign tables.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Also enable this for postgres_fdw.

Etsuro Fujita, based on an earlier patch by Amit Langote. The larger
patch series of which this is a part has been reviewed by Amit
Langote, David Fetter, Maksim Milyutin, Álvaro Herrera, Stephen Frost,
and me.  Minor documentation changes to the final version by me.

Discussion: http://postgr.es/m/29906a26-da12-8c86-4fb9-d8f88442f2b9@lab.ntt.co.jp
---
 doc/src/sgml/ddl.sgml        |  8 ++----
 doc/src/sgml/fdwhandler.sgml | 66 ++++++++++++++++++++++++++++++++++++++++++++
 doc/src/sgml/ref/copy.sgml   |  5 ++--
 doc/src/sgml/ref/update.sgml |  3 ++
 4 files changed, 75 insertions(+), 7 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 8805b88d829..206cc3a835d 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3037,11 +3037,9 @@ VALUES ('Albany', NULL, NULL, 'NY');
    </para>
 
    <para>
-    Partitions can also be foreign tables
-    (see <xref linkend="sql-createforeigntable"/>),
-    although these have some limitations that normal tables do not.  For
-    example, data inserted into the partitioned table is not routed to
-    foreign table partitions.
+    Partitions can also be foreign tables, although they have some limitations
+    that normal tables do not; see <xref linkend="sql-createforeigntable"> for
+    more information.
    </para>
 
    <para>
diff --git a/doc/src/sgml/fdwhandler.sgml b/doc/src/sgml/fdwhandler.sgml
index b1f16f3cbad..7b758bdf09b 100644
--- a/doc/src/sgml/fdwhandler.sgml
+++ b/doc/src/sgml/fdwhandler.sgml
@@ -694,6 +694,72 @@ EndForeignModify(EState *estate,
      <literal>NULL</literal>, no action is taken during executor shutdown.
     </para>
 
+    <para>
+     Tuples inserted into a partitioned table by <command>INSERT</command> or
+     <command>COPY FROM</command> are routed to partitions.  If an FDW
+     supports routable foreign-table partitions, it should also provide the
+     following callback functions.  These functions are also called when
+     <command>COPY FROM</command> is executed on a foreign table.
+    </para>
+
+    <para>
+<programlisting>
+void
+BeginForeignInsert(ModifyTableState *mtstate,
+                   ResultRelInfo *rinfo);
+</programlisting>
+
+     Begin executing an insert operation on a foreign table.  This routine is
+     called right before the first tuple is inserted into the foreign table
+     in both cases when it is the partition chosen for tuple routing and the
+     target specified in a <command>COPY FROM</command> command.  It should
+     perform any initialization needed prior to the actual insertion.
+     Subsequently, <function>ExecForeignInsert</function> will be called for
+     each tuple to be inserted into the foreign table.
+    </para>
+
+    <para>
+     <literal>mtstate</literal> is the overall state of the
+     <structname>ModifyTable</structname> plan node being executed; global data about
+     the plan and execution state is available via this structure.
+     <literal>rinfo</literal> is the <structname>ResultRelInfo</structname> struct describing
+     the target foreign table.  (The <structfield>ri_FdwState</structfield> field of
+     <structname>ResultRelInfo</structname> is available for the FDW to store any
+     private state it needs for this operation.)
+    </para>
+
+    <para>
+     When this is called by a <command>COPY FROM</command> command, the
+     plan-related global data in <literal>mtstate</literal> is not provided
+     and the <literal>planSlot</literal> parameter of
+     <function>ExecForeignInsert</function> subsequently called for each
+     inserted tuple is <literal>NULL</literal>, whether the foreign table is
+     the partition chosen for tuple routing or the target specified in the
+     command.
+    </para>
+
+    <para>
+     If the <function>BeginForeignInsert</function> pointer is set to
+     <literal>NULL</literal>, no action is taken for the initialization.
+    </para>
+
+    <para>
+<programlisting>
+void
+EndForeignInsert(EState *estate,
+                 ResultRelInfo *rinfo);
+</programlisting>
+
+     End the insert operation and release resources.  It is normally not important
+     to release palloc'd memory, but for example open files and connections
+     to remote servers should be cleaned up.
+    </para>
+
+    <para>
+     If the <function>EndForeignInsert</function> pointer is set to
+     <literal>NULL</literal>, no action is taken for the termination.
+    </para>
+
     <para>
 <programlisting>
 int
diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml
index 344d391e4aa..13a8b68d951 100644
--- a/doc/src/sgml/ref/copy.sgml
+++ b/doc/src/sgml/ref/copy.sgml
@@ -402,8 +402,9 @@ COPY <replaceable class="parameter">count</replaceable>
    </para>
 
    <para>
-    <command>COPY FROM</command> can be used with plain tables and with views
-    that have <literal>INSTEAD OF INSERT</literal> triggers.
+    <command>COPY FROM</command> can be used with plain, foreign, or
+    partitioned tables or with views that have
+    <literal>INSTEAD OF INSERT</literal> triggers.
    </para>
 
    <para>
diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml
index c8ac8a335b8..77430a586cb 100644
--- a/doc/src/sgml/ref/update.sgml
+++ b/doc/src/sgml/ref/update.sgml
@@ -291,6 +291,9 @@ UPDATE <replaceable class="parameter">count</replaceable>
    concurrent <command>UPDATE</command> or <command>DELETE</command> on the
    same row may miss this row. For details see the section
    <xref linkend="ddl-partitioning-declarative-limitations"/>.
+   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.
   </para>
  </refsect1>
 
-- 
cgit v1.2.3