Implement IMPORT FOREIGN SCHEMA.

This command provides an automated way to create foreign table definitions
that match remote tables, thereby reducing tedium and chances for error.
In this patch, we provide the necessary core-server infrastructure and
implement the feature fully in the postgres_fdw foreign-data wrapper.
Other wrappers will throw a "feature not supported" error until/unless
they are updated.

Ronan Dunklau and Michael Paquier, additional work by me

doc/src/sgml/postgres-fdw.sgml

@@ -49,7 +49,8 @@
    </listitem>
    <listitem>
     <para>
-     Create a foreign table, using <xref linkend="sql-createforeigntable">,
+     Create a foreign table, using <xref linkend="sql-createforeigntable">
+     or <xref linkend="sql-importforeignschema">,
      for each remote table you want to access.  The columns of the foreign
      table must match the referenced remote table.  You can, however, use
      table and/or column names different from the remote table's, if you
@@ -99,7 +100,7 @@
      <listitem>
       <para>
        <literal>user</literal> and <literal>password</literal> (specify these
-       for a user mapping, instead)
+       in a user mapping, instead)
       </para>
      </listitem>
      <listitem>
@@ -291,6 +292,72 @@
 
    </variablelist>
   </sect3>
+
+  <sect3>
+   <title>Importing Options</title>
+
+   <para>
+    <filename>postgres_fdw</> is able to import foreign table definitions
+    using <xref linkend="sql-importforeignschema">.  This command creates
+    foreign table definitions on the local server that match tables or
+    views present on the remote server.  If the remote tables to be imported
+    have columns of user-defined data types, the local server must have types
+    of the same names.
+   </para>
+
+   <para>
+    Importing behavior can be customized with the following options
+    (given in the <command>IMPORT FOREIGN SCHEMA</> command):
+   </para>
+
+   <variablelist>
+    <varlistentry>
+     <term><literal>import_collate</literal></term>
+     <listitem>
+      <para>
+       This option controls whether column <literal>COLLATE</> options
+       are included in the definitions of foreign tables imported
+       from a foreign server. The default is <literal>true</>.  You might
+       need to turn this off if the remote server has a different set of
+       collation names than the local server does, which is likely to be the
+       case if it's running on a different operating system.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><literal>import_default</literal></term>
+     <listitem>
+      <para>
+       This option controls whether column <literal>DEFAULT</> expressions
+       are included in the definitions of foreign tables imported
+       from a foreign server. The default is <literal>false</>.  If you
+       enable this option, be wary of defaults that might get computed
+       differently on the local server than they would be on the remote
+       server; <function>nextval()</> is a common source of problems.
+       The <command>IMPORT</> will fail altogether if an imported default
+       expression uses a function or operator that does not exist locally.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><literal>import_not_null</literal></term>
+     <listitem>
+      <para>
+       This option controls whether column <literal>NOT NULL</>
+       constraints are included in the definitions of foreign tables imported
+       from a foreign server. The default is <literal>true</>.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+
+   <para>
+    Note that constraints other than <literal>NOT NULL</> will never be
+    imported from the remote tables, since <productname>PostgreSQL</>
+    does not support any other type of constraint on a foreign table.
+    Checking other types of constraints is always left to the remote server.
+   </para>
+  </sect3>
  </sect2>
 
  <sect2>
@@ -422,7 +489,7 @@ CREATE USER MAPPING FOR local_user
 
 <programlisting>
 CREATE FOREIGN TABLE foreign_table (
-        id serial NOT NULL,
+        id integer NOT NULL,
         data text
 )
         SERVER foreign_server
@@ -434,6 +501,8 @@ CREATE FOREIGN TABLE foreign_table (
    Column names must match as well, unless you attach <literal>column_name</>
    options to the individual columns to show how they are named in the remote
    table.
+   In many cases, use of <xref linkend="sql-importforeignschema"> is
+   preferable to constructing foreign table definitions manually.
   </para>
  </sect2>