Allow TRUNCATE command to truncate foreign tables.

This commit introduces new foreign data wrapper API for TRUNCATE.
It extends TRUNCATE command so that it accepts foreign tables as
the targets to truncate and invokes that API. Also it extends postgres_fdw
so that it can issue TRUNCATE command to foreign servers, by adding
new routine for that TRUNCATE API.

The information about options specified in TRUNCATE command, e.g.,
ONLY, CACADE, etc is passed to FDW via API. The list of foreign tables to
truncate is also passed to FDW. FDW truncates the foreign data sources
that the passed foreign tables specify, based on those information.
For example, postgres_fdw constructs TRUNCATE command using them
and issues it to the foreign server.

For performance, TRUNCATE command invokes the FDW routine for
TRUNCATE once per foreign server that foreign tables to truncate belong to.

Author: Kazutaka Onishi, Kohei KaiGai, slightly modified by Fujii Masao
Reviewed-by: Bharath Rupireddy, Michael Paquier, Zhihong Yu, Alvaro Herrera, Stephen Frost, Ashutosh Bapat, Amit Langote, Daniel Gustafsson, Ibrar Ahmed, Fujii Masao
Discussion: https://postgr.es/m/CAOP8fzb_gkReLput7OvOK+8NHgw-RKqNv59vem7=524krQTcWA@mail.gmail.com
Discussion: https://postgr.es/m/CAJuF6cMWDDqU-vn_knZgma+2GMaout68YUgn1uyDnexRhqqM5Q@mail.gmail.com

3 files changed, 93 insertions, 6 deletions

diff --git a/doc/src/sgml/fdwhandler.sgml b/doc/src/sgml/fdwhandler.sgml
index 0f2397df497..98882ddab86 100644
--- a/doc/src/sgml/fdwhandler.sgml
+++ b/doc/src/sgml/fdwhandler.sgml
@@ -1065,6 +1065,67 @@ EndDirectModify(ForeignScanState *node);
 
    </sect2>
 
+   <sect2 id="fdw-callbacks-truncate">
+    <title>FDW Routines for <command>TRUNCATE</command></title>
+
+    <para>
+<programlisting>
+void
+ExecForeignTruncate(List *rels, List *rels_extra,
+                    DropBehavior behavior, bool restart_seqs);
+</programlisting>
+
+     Truncate a set of foreign tables specified in <literal>rels</literal>.
+     This function is called when <xref linkend="sql-truncate"/> is executed
+     on foreign tables.  <literal>rels</literal> is the list of
+     <structname>Relation</structname> data structure that indicates
+     a foreign table to truncate.  <literal>rels_extra</literal> the list of
+     <literal>int</literal> value, which delivers extra information about
+     a foreign table to truncate.  Possible values are
+     <literal>TRUNCATE_REL_CONTEXT_NORMAL</literal>, which means that
+     the foreign table is specified WITHOUT <literal>ONLY</literal> clause
+     in <command>TRUNCATE</command>,
+     <literal>TRUNCATE_REL_CONTEXT_ONLY</literal>, which means that
+     the foreign table is specified WITH <literal>ONLY</literal> clause,
+     and <literal>TRUNCATE_REL_CONTEXT_CASCADING</literal>,
+     which means that the foreign table is not specified explicitly,
+     but will be truncated due to dependency (for example, partition table).
+     There is one-to-one mapping between <literal>rels</literal> and
+     <literal>rels_extra</literal>.  The number of entries is the same
+     between the two lists.
+    </para>
+
+    <para>
+     <literal>behavior</literal> defines how foreign tables should
+     be truncated, using as possible values <literal>DROP_RESTRICT</literal>,
+     which means that <literal>RESTRICT</literal> option is specified,
+     and <literal>DROP_CASCADE</literal>, which means that
+     <literal>CASCADE</literal> option is specified, in
+     <command>TRUNCATE</command> command.
+    </para>
+    
+    <para>
+     <literal>restart_seqs</literal> is set to <literal>true</literal>
+     if <literal>RESTART IDENTITY</literal> option is specified in
+     <command>TRUNCATE</command> command.  It is <literal>false</literal>
+     if <literal>CONTINUE IDENTITY</literal> option is specified.
+    </para>
+
+    <para>
+     <command>TRUNCATE</command> invokes
+     <function>ExecForeignTruncate</function> once per foreign server
+     that foreign tables to truncate belong to.  This means that all foreign
+     tables included in <literal>rels</literal> must belong to the same
+     server.
+    </para>
+
+    <para>
+     If the <function>ExecForeignTruncate</function> pointer is set to
+     <literal>NULL</literal>, attempts to truncate foreign tables will
+     fail with an error message.
+    </para>
+   </sect2>
+
    <sect2 id="fdw-callbacks-row-locking">
     <title>FDW Routines for Row Locking</title>
 
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index b0792a13b13..fd349569369 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -63,9 +63,10 @@
  <para>
   Now you need only <command>SELECT</command> from a foreign table to access
   the data stored in its underlying remote table.  You can also modify
-  the remote table using <command>INSERT</command>, <command>UPDATE</command>, or
-  <command>DELETE</command>.  (Of course, the remote user you have specified
-  in your user mapping must have privileges to do these things.)
+  the remote table using <command>INSERT</command>, <command>UPDATE</command>,
+  <command>DELETE</command>, or <command>TRUNCATE</command>.
+  (Of course, the remote user you have specified in your user mapping must
+  have privileges to do these things.)
  </para>
 
  <para>
@@ -437,6 +438,31 @@ OPTIONS (ADD password_required 'false');
   </sect3>
 
   <sect3>
+   <title>Truncatability Options</title>
+
+   <para>
+    By default all foreign tables using <filename>postgres_fdw</filename> are assumed
+    to be truncatable.  This may be overridden using the following option:
+   </para>
+
+   <variablelist>
+
+    <varlistentry>
+     <term><literal>truncatable</literal></term>
+     <listitem>
+      <para>
+       This option controls whether <filename>postgres_fdw</filename> allows
+       foreign tables to be truncated using <command>TRUNCATE</command>
+       command. It can be specified for a foreign table or a foreign server.
+       A table-level option overrides a server-level option.
+       The default is <literal>true</literal>.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </sect3>
+
+  <sect3>
    <title>Importing Options</title>
 
    <para>
diff --git a/doc/src/sgml/ref/truncate.sgml b/doc/src/sgml/ref/truncate.sgml
index 91cdac55623..acf3633be46 100644
--- a/doc/src/sgml/ref/truncate.sgml
+++ b/doc/src/sgml/ref/truncate.sgml
@@ -172,9 +172,9 @@ TRUNCATE [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [
   </para>
 
   <para>
-   <command>TRUNCATE</command> is not currently supported for foreign tables.
-   This implies that if a specified table has any descendant tables that are
-   foreign, the command will fail.
+   <command>TRUNCATE</command> can be used for foreign tables if
+   the foreign data wrapper supports, for instance,
+   see <xref linkend="postgres-fdw"/>.
   </para>
  </refsect1>