Add postgres_fdw contrib module.

There's still a lot of room for improvement, but it basically works,
and we need this to be present before we can do anything much with the
writable-foreign-tables patch.  So let's commit it and get on with testing.

Shigeru Hanada, reviewed by KaiGai Kohei and Tom Lane

doc/src/sgml/ref/create_foreign_data_wrapper.sgml

@@ -121,14 +121,6 @@ CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
    There is no support for updating a foreign table, and optimization of
    queries is primitive (and mostly left to the wrapper, too).
   </para>
-
-  <para>
-   There is one built-in foreign-data wrapper validator function
-   provided:
-   <filename>postgresql_fdw_validator</filename>, which accepts
-   options corresponding to <application>libpq</> connection
-   parameters.
-  </para>
  </refsect1>
 
  <refsect1>

doc/src/sgml/ref/create_foreign_table.sgml

@@ -32,7 +32,7 @@ CREATE FOREIGN TABLE [ IF NOT EXISTS ] <replaceable class="PARAMETER">table_name
   <title>Description</title>
 
   <para>
-   <command>CREATE FOREIGN TABLE</command> will create a new foreign table
+   <command>CREATE FOREIGN TABLE</command> creates a new foreign table
    in the current database. The table will be owned by the user issuing the
    command.
   </para>
@@ -54,8 +54,9 @@ CREATE FOREIGN TABLE [ IF NOT EXISTS ] <replaceable class="PARAMETER">table_name
   </para>
 
   <para>
-   To be able to create a table, you must have <literal>USAGE</literal>
-   privilege on all column types.
+   To be able to create a foreign table, you must have <literal>USAGE</literal>
+   privilege on the foreign server, as well as <literal>USAGE</literal>
+   privilege on all column types used in the table.
   </para>
  </refsect1>
 
@@ -134,7 +135,7 @@ CREATE FOREIGN TABLE [ IF NOT EXISTS ] <replaceable class="PARAMETER">table_name
     <term><replaceable class="PARAMETER">server_name</replaceable></term>
     <listitem>
      <para>
-      The name of an existing server for the foreign table.
+      The name of an existing foreign server to use for the foreign table.
       For details on defining a server, see <xref
       linkend="SQL-CREATESERVER">.
      </para>
@@ -164,7 +165,8 @@ CREATE FOREIGN TABLE [ IF NOT EXISTS ] <replaceable class="PARAMETER">table_name
   <title>Examples</title>
 
   <para>
-   Create foreign table <structname>films</> with <structname>film_server</>:
+   Create foreign table <structname>films</>, which will be accessed through
+   the server <structname>film_server</>:
 
 <programlisting>
 CREATE FOREIGN TABLE films (

doc/src/sgml/ref/create_server.sgml

@@ -110,11 +110,10 @@ CREATE SERVER <replaceable class="parameter">server_name</replaceable> [ TYPE '<
   <title>Notes</title>
 
   <para>
-   When using the <application>dblink</application> module
-   (see <xref linkend="dblink">), the foreign server name can be used
+   When using the <xref linkend="dblink"> module,
+   a foreign server's name can be used
    as an argument of the <xref linkend="contrib-dblink-connect">
-   function to indicate the connection parameters.  See also there for
-   more examples.  It is necessary to have
+   function to indicate the connection parameters.  It is necessary to have
    the <literal>USAGE</literal> privilege on the foreign server to be
    able to use it in this way.
   </para>
@@ -123,20 +122,14 @@ CREATE SERVER <replaceable class="parameter">server_name</replaceable> [ TYPE '<
  <refsect1>
   <title>Examples</title>
 
-  <para>
-   Create a server <literal>foo</> that uses the built-in foreign-data
-   wrapper <literal>default</>:
-<programlisting>
-CREATE SERVER foo FOREIGN DATA WRAPPER "default";
-</programlisting>
-  </para>
-
   <para>
    Create a server <literal>myserver</> that uses the
-   foreign-data wrapper <literal>pgsql</>:
+   foreign-data wrapper <literal>postgres_fdw</>:
 <programlisting>
-CREATE SERVER myserver FOREIGN DATA WRAPPER pgsql OPTIONS (host 'foo', dbname 'foodb', port '5432');
-</programlisting></para>
+CREATE SERVER myserver FOREIGN DATA WRAPPER postgres_fdw OPTIONS (host 'foo', dbname 'foodb', port '5432');
+</programlisting>
+   See <xref linkend="postgres-fdw"> for more details.
+  </para>
  </refsect1>
 
  <refsect1>
@@ -154,6 +147,7 @@ CREATE SERVER myserver FOREIGN DATA WRAPPER pgsql OPTIONS (host 'foo', dbname 'f
    <member><xref linkend="sql-alterserver"></member>
    <member><xref linkend="sql-dropserver"></member>
    <member><xref linkend="sql-createforeigndatawrapper"></member>
+   <member><xref linkend="sql-createforeigntable"></member>
    <member><xref linkend="sql-createusermapping"></member>
   </simplelist>
  </refsect1>

doc/src/sgml/ref/grant.sgml

@@ -357,10 +357,9 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace
        to create new servers using that foreign-data wrapper.
       </para>
       <para>
-       For servers, this privilege enables the grantee to create,
-       alter, and drop his own user's user mappings associated with
-       that server.  Also, it enables the grantee to query the options
-       of the server and associated user mappings.
+       For servers, this privilege enables the grantee to create foreign
+       tables using the server, and also to create, alter, or drop his own
+       user's user mappings associated with that server.
       </para>
      </listitem>
     </varlistentry>

doc/src/sgml/ref/pg_isready.sgml

@@ -54,7 +54,8 @@ PostgreSQL documentation
        with a valid <acronym>URI</acronym> prefix
        (<literal>postgresql://</literal>
        or <literal>postgres://</literal>), it is treated as a
-       <parameter>conninfo</parameter> string. See <xref linkend="libpq-connect"> for more information.
+       <parameter>conninfo</parameter> string. See <xref
+       linkend="libpq-connstring"> for more information.
       </para>
       </listitem>
     </varlistentry>

doc/src/sgml/ref/psql-ref.sgml

@@ -120,7 +120,8 @@ PostgreSQL documentation
        with a valid <acronym>URI</acronym> prefix
        (<literal>postgresql://</literal>
        or <literal>postgres://</literal>), it is treated as a
-       <parameter>conninfo</parameter> string. See <xref linkend="libpq-connect"> for more information.
+       <parameter>conninfo</parameter> string. See <xref
+       linkend="libpq-connstring"> for more information.
       </para>
       </listitem>
     </varlistentry>
@@ -608,9 +609,9 @@ PostgreSQL documentation
 $ <userinput>psql "service=myservice sslmode=require"</userinput>
 $ <userinput>psql postgresql://dbmaster:5433/mydb?sslmode=require</userinput>
 </programlisting>
-     This way you can also use <acronym>LDAP</acronym> for connection parameter lookup as
-     described in <xref linkend="libpq-ldap">.
-     See <xref linkend="libpq-connect"> for more information on all the
+     This way you can also use <acronym>LDAP</acronym> for connection
+     parameter lookup as described in <xref linkend="libpq-ldap">.
+     See <xref linkend="libpq-paramkeywords"> for more information on all the
      available connection options.
     </para>