Create the catalog infrastructure for foreign-data-wrapper handlers.

Add a fdwhandler column to pg_foreign_data_wrapper, plus HANDLER options
in the CREATE FOREIGN DATA WRAPPER and ALTER FOREIGN DATA WRAPPER commands,
plus pg_dump support for same.  Also invent a new pseudotype fdw_handler
with properties similar to language_handler.

This is split out of the "FDW API" patch for ease of review; it's all stuff
we will certainly need, regardless of any other details of the FDW API.
FDW handler functions will not actually get called yet.

In passing, fix some omissions and infelicities in foreigncmds.c.

Shigeru Hanada, Jan Urbanski, Heikki Linnakangas

4 files changed, 101 insertions, 35 deletions

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 30f39806970..88eaca0bea0 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -3032,15 +3032,26 @@
      </row>
 
      <row>
+      <entry><structfield>fdwhandler</structfield></entry>
+      <entry><type>oid</type></entry>
+      <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
+      <entry>
+       References a handler function that is responsible for
+       supplying execution routines for the foreign-data wrapper.
+       Zero if no handler is provided
+      </entry>
+     </row>
+
+     <row>
       <entry><structfield>fdwvalidator</structfield></entry>
       <entry><type>oid</type></entry>
       <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
       <entry>
        References a validator function that is responsible for
-       checking the validity of the generic options given to the
-       foreign-data wrapper, as well as to foreign servers and user
+       checking the validity of the options given to the
+       foreign-data wrapper, as well as options for foreign servers and user
        mappings using the foreign-data wrapper.  Zero if no validator
-       is provided.
+       is provided
       </entry>
      </row>
 
@@ -3079,8 +3090,8 @@
 
   <para>
    The catalog <structname>pg_foreign_server</structname> stores
-   foreign server definitions.  A foreign server describes the
-   connection to a remote server, managing external data.  Foreign
+   foreign server definitions.  A foreign server describes a source
+   of external data, such as a remote server.  Foreign
    servers are accessed via foreign-data wrappers.
   </para>
 
@@ -3116,7 +3127,7 @@
       <entry><structfield>srvfdw</structfield></entry>
       <entry><type>oid</type></entry>
       <entry><literal><link linkend="catalog-pg-foreign-data-wrapper"><structname>pg_foreign_data_wrapper</structname></link>.oid</literal></entry>
-      <entry>The OID of the foreign-data wrapper of this foreign server</entry>
+      <entry>OID of the foreign-data wrapper of this foreign server</entry>
      </row>
 
      <row>
@@ -3167,9 +3178,12 @@
   </indexterm>
 
   <para>
-   The catalog <structname>pg_foreign_table</structname> contains part
-   of the information about foreign tables.
-   The rest is mostly in <structname>pg_class</structname>.
+   The catalog <structname>pg_foreign_table</structname> contains
+   auxiliary information about foreign tables.  A foreign table is
+   primarily represented by a <structname>pg_class</structname> entry,
+   just like a regular table.  Its <structname>pg_foreign_table</structname>
+   entry contains the information that is pertinent only to foreign tables
+   and not any other kind of relation.
   </para>
 
   <table>
@@ -3190,14 +3204,14 @@
       <entry><structfield>ftrelid</structfield></entry>
       <entry><type>oid</type></entry>
       <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry>
-      <entry>The OID of the <structname>pg_class</> entry for this foreign table</entry>
+      <entry>OID of the <structname>pg_class</> entry for this foreign table</entry>
      </row>
 
      <row>
       <entry><structfield>ftserver</structfield></entry>
       <entry><type>oid</type></entry>
       <entry><literal><link linkend="catalog-pg-foreign-server"><structname>pg_foreign_server</structname></link>.oid</literal></entry>
-      <entry>The OID of the foreign server for this foreign table</entry>
+      <entry>OID of the foreign server for this foreign table</entry>
      </row>
 
      <row>
@@ -3205,7 +3219,7 @@
       <entry><type>text[]</type></entry>
       <entry></entry>
       <entry>
-       Foreign table options, as <quote>keyword=value</> strings.
+       Foreign table options, as <quote>keyword=value</> strings
       </entry>
      </row>
     </tbody>
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 253b7578985..b8f6e238f0b 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -4432,6 +4432,10 @@ SELECT * FROM pg_attribute
    </indexterm>
 
    <indexterm zone="datatype-pseudo">
+    <primary>fdw_handler</primary>
+   </indexterm>
+
+   <indexterm zone="datatype-pseudo">
     <primary>cstring</primary>
    </indexterm>
 
@@ -4514,6 +4518,11 @@ SELECT * FROM pg_attribute
        </row>
 
        <row>
+        <entry><type>fdw_handler</></entry>
+        <entry>A foreign-data wrapper handler is declared to return <type>fdw_handler</>.</entry>
+       </row>
+
+       <row>
         <entry><type>record</></entry>
         <entry>Identifies a function returning an unspecified row type.</entry>
        </row>
diff --git a/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml b/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml
index 4e9e8a2e28a..af56ed7561d 100644
--- a/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml
+++ b/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml
@@ -22,7 +22,8 @@ PostgreSQL documentation
  <refsynopsisdiv>
 <synopsis>
 ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
-    [ VALIDATOR <replaceable class="parameter">valfunction</replaceable> | NO VALIDATOR ]
+    [ HANDLER <replaceable class="parameter">handler_function</replaceable> | NO HANDLER ]
+    [ VALIDATOR <replaceable class="parameter">validator_function</replaceable> | NO VALIDATOR ]
     [ OPTIONS ( [ ADD | SET | DROP ] <replaceable class="PARAMETER">option</replaceable> ['<replaceable class="PARAMETER">value</replaceable>'] [, ... ]) ]
 ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> OWNER TO <replaceable>new_owner</replaceable>
 </synopsis>
@@ -34,7 +35,7 @@ ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> OWN
   <para>
    <command>ALTER FOREIGN DATA WRAPPER</command> changes the
    definition of a foreign-data wrapper.  The first form of the
-   command changes the library or the generic options of the
+   command changes the support functions or the generic options of the
    foreign-data wrapper (at least one clause is required).  The second
    form changes the owner of the foreign-data wrapper.
   </para>
@@ -59,10 +60,33 @@ ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> OWN
    </varlistentry>
 
    <varlistentry>
-    <term><literal>VALIDATOR <replaceable class="parameter">valfunction</replaceable></literal></term>
+    <term><literal>HANDLER <replaceable class="parameter">handler_function</replaceable></literal></term>
     <listitem>
      <para>
-      Specifies a new foreign-data wrapper validator function.
+      Specifies a new handler function for the foreign-data wrapper.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><literal>NO HANDLER</literal></term>
+    <listitem>
+     <para>
+      This is used to specify that the foreign-data wrapper should no
+      longer have a handler function.
+     </para>
+     <para>
+      Note that foreign tables that use a foreign-data wrapper with no
+      handler cannot be accessed.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><literal>VALIDATOR <replaceable class="parameter">validator_function</replaceable></literal></term>
+    <listitem>
+     <para>
+      Specifies a new validator function for the foreign-data wrapper.
      </para>
 
      <para>
@@ -94,7 +118,7 @@ ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> OWN
       specify the action to be performed.  <literal>ADD</> is assumed
       if no operation is explicitly specified.  Option names must be
       unique; names and values are also validated using the foreign
-      data wrapper library.
+      data wrapper's validator function, if any.
      </para>
     </listitem>
    </varlistentry>
@@ -126,9 +150,8 @@ ALTER FOREIGN DATA WRAPPER dbi VALIDATOR bob.myvalidator;
 
   <para>
    <command>ALTER FOREIGN DATA WRAPPER</command> conforms to ISO/IEC
-   9075-9 (SQL/MED).  The standard does not specify the <literal>
-   VALIDATOR</literal> and <literal>OWNER TO</> variants of the
-   command.
+   9075-9 (SQL/MED), except that the <literal>HANDLER</literal>,
+   <literal>VALIDATOR</> and <literal>OWNER TO</> clauses are extensions.
   </para>
  </refsect1>
 
diff --git a/doc/src/sgml/ref/create_foreign_data_wrapper.sgml b/doc/src/sgml/ref/create_foreign_data_wrapper.sgml
index f626d56665b..711f32b118b 100644
--- a/doc/src/sgml/ref/create_foreign_data_wrapper.sgml
+++ b/doc/src/sgml/ref/create_foreign_data_wrapper.sgml
@@ -22,7 +22,8 @@ PostgreSQL documentation
  <refsynopsisdiv>
 <synopsis>
 CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
-    [ VALIDATOR <replaceable class="parameter">valfunction</replaceable> | NO VALIDATOR ]
+    [ HANDLER <replaceable class="parameter">handler_function</replaceable> | NO HANDLER ]
+    [ VALIDATOR <replaceable class="parameter">validator_function</replaceable> | NO VALIDATOR ]
     [ OPTIONS ( <replaceable class="PARAMETER">option</replaceable> '<replaceable class="PARAMETER">value</replaceable>' [, ... ] ) ]
 </synopsis>
  </refsynopsisdiv>
@@ -59,13 +60,32 @@ CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
    </varlistentry>
 
    <varlistentry>
-    <term><literal>VALIDATOR <replaceable class="parameter">valfunction</replaceable></literal></term>
+    <term><literal>HANDLER <replaceable class="parameter">handler_function</replaceable></literal></term>
     <listitem>
      <para>
-      <replaceable class="parameter">valfunction</replaceable> is the
+      <replaceable class="parameter">handler_function</replaceable> is the
+      name of a previously registered function that will be called to
+      retrieve the execution functions for foreign tables.
+      The handler function must take no arguments, and
+      its return type must be <type>fdw_handler</type>.
+     </para>
+
+     <para>
+      It is possible to create a foreign-data wrapper with no handler
+      function, but foreign tables using such a wrapper can only be declared,
+      not accessed.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><literal>VALIDATOR <replaceable class="parameter">validator_function</replaceable></literal></term>
+    <listitem>
+     <para>
+      <replaceable class="parameter">validator_function</replaceable> is the
       name of a previously registered function that will be called to
       check the generic options given to the foreign-data wrapper, as
-      well as to foreign servers and user mappings using the
+      well as options for foreign servers and user mappings using the
       foreign-data wrapper.  If no validator function or <literal>NO
       VALIDATOR</literal> is specified, then options will not be
       checked at creation time.  (Foreign-data wrappers will possibly
@@ -75,8 +95,8 @@ CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
       contain the array of options as stored in the system catalogs,
       and one of type <type>oid</type>, which will be the OID of the
       system catalog containing the options. The return type is ignored;
-      the function should indicate invalid options using the
-      <function>ereport()</function> function.
+      the function should report invalid options using the
+      <function>ereport(ERROR)</function> function.
      </para>
     </listitem>
    </varlistentry>
@@ -87,8 +107,8 @@ CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
      <para>
       This clause specifies options for the new foreign-data wrapper.
       The allowed option names and values are specific to each foreign
-      data wrapper and are validated using the foreign-data wrapper
-      library.  Option names must be unique.
+      data wrapper and are validated using the foreign-data wrapper's
+      validator function.  Option names must be unique.
      </para>
     </listitem>
    </varlistentry>
@@ -122,17 +142,17 @@ CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
   <title>Examples</title>
 
   <para>
-   Create a foreign-data wrapper <literal>dummy</>:
+   Create a useless foreign-data wrapper <literal>dummy</>:
 <programlisting>
 CREATE FOREIGN DATA WRAPPER dummy;
 </programlisting>
   </para>
 
   <para>
-   Create a foreign-data wrapper <literal>postgresql</> with
-   validator function <literal>postgresql_fdw_validator</>:
+   Create a foreign-data wrapper <literal>file</> with
+   handler function <literal>file_fdw_handler</>:
 <programlisting>
-CREATE FOREIGN DATA WRAPPER postgresql VALIDATOR postgresql_fdw_validator;
+CREATE FOREIGN DATA WRAPPER file HANDLER file_fdw_handler;
 </programlisting>
   </para>
 
@@ -151,10 +171,10 @@ CREATE FOREIGN DATA WRAPPER mywrapper
 
   <para>
    <command>CREATE FOREIGN DATA WRAPPER</command> conforms to ISO/IEC
-   9075-9 (SQL/MED), with the exception that
-   the <literal>VALIDATOR</literal> clause is an extension and the
+   9075-9 (SQL/MED), with the exception that the <literal>HANDLER</literal>
+   and <literal>VALIDATOR</literal> clauses are extensions and the standard
    clauses <literal>LIBRARY</literal> and <literal>LANGUAGE</literal>
-   are not yet implemented in PostgreSQL.
+   are not implemented in PostgreSQL.
   </para>
 
   <para>