From 9405b16f3a2c8d504f7be15912d9cd00261449fb Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Thu, 18 Jun 2009 14:34:36 +0000
Subject: [PATCH] Add some more documentation and cross-links on using dblink
 with SQL/MED.

---
 doc/src/sgml/dblink.sgml                      | 10 ++++----
 .../sgml/ref/create_foreign_data_wrapper.sgml |  6 +++--
 doc/src/sgml/ref/create_server.sgml           | 23 ++++++++++++++++++-
 doc/src/sgml/ref/create_user_mapping.sgml     | 12 ++++++----
 4 files changed, 40 insertions(+), 11 deletions(-)

diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml
index 06fcc8cee8..2afa40a29f 100644
--- a/doc/src/sgml/dblink.sgml
+++ b/doc/src/sgml/dblink.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/dblink.sgml,v 1.7 2009/06/06 21:27:56 joe Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/dblink.sgml,v 1.8 2009/06/18 14:34:36 petere Exp $ -->
 
 <sect1 id="dblink">
  <title>dblink</title>
@@ -45,8 +45,10 @@
 
    <para>
     The connection string may also be the name of an existing foreign
-    server that utilizes the postgresql_fdw foreign data wrapper library.
-    See the example below, as well as the following:
+    server.  It is recommended to use
+    the <function>postgresql_fdw_validator</function> when defining
+    the corresponding foreign-data wrapper.  See the example below, as
+    well as the following:
     <simplelist type="inline">
      <member><xref linkend="sql-createforeigndatawrapper" endterm="sql-createforeigndatawrapper-title"></member>
      <member><xref linkend="sql-createserver" endterm="sql-createserver-title"></member>
@@ -134,7 +136,7 @@
  --       DETAIL:  Non-superuser cannot connect if the server does not request a password.
  --       HINT:  Target server's authentication method must be changed.
  CREATE USER dblink_regression_test WITH PASSWORD 'secret';
- CREATE FOREIGN DATA WRAPPER postgresql;
+ CREATE FOREIGN DATA WRAPPER postgresql VALIDATOR postgresql_fdw_validator;
  CREATE SERVER fdtest FOREIGN DATA WRAPPER postgresql OPTIONS (hostaddr '127.0.0.1', dbname 'contrib_regression');
 
  CREATE USER MAPPING FOR dblink_regression_test SERVER fdtest OPTIONS (user 'dblink_regression_test', password 'secret');
diff --git a/doc/src/sgml/ref/create_foreign_data_wrapper.sgml b/doc/src/sgml/ref/create_foreign_data_wrapper.sgml
index bc615476bd..dd48245372 100644
--- a/doc/src/sgml/ref/create_foreign_data_wrapper.sgml
+++ b/doc/src/sgml/ref/create_foreign_data_wrapper.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_foreign_data_wrapper.sgml,v 1.3 2009/02/27 07:20:00 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_foreign_data_wrapper.sgml,v 1.4 2009/06/18 14:34:36 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -103,7 +103,9 @@ CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
    rudimentary.  The purpose of foreign-data wrappers, foreign
    servers, and user mappings is to store this information in a
    standard way so that it can be queried by interested applications.
-   The functionality to actually query external data does not exist
+   One such application is <application>dblink</application>;
+   see <xref linkend="dblink">.  The functionality to actually query
+   external data through a foreign-data wrapper library does not exist
    yet.
   </para>
 
diff --git a/doc/src/sgml/ref/create_server.sgml b/doc/src/sgml/ref/create_server.sgml
index c588e6b3e6..c828c5a28b 100644
--- a/doc/src/sgml/ref/create_server.sgml
+++ b/doc/src/sgml/ref/create_server.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_server.sgml,v 1.3 2009/02/27 07:20:00 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_server.sgml,v 1.4 2009/06/18 14:34:36 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -34,6 +34,13 @@ CREATE SERVER <replaceable class="parameter">servername</replaceable> [ TYPE 'se
    user who defines the server becomes its owner.
   </para>
 
+  <para>
+   A foreign server typically encapsulates connection information that
+   a foreign-data wrapper uses to access an external data resource.
+   Additional user-specific connection information may be specified by
+   means of user mappings.
+  </para>
+
   <para>
    The server name must be unique within the database.
   </para>
@@ -98,6 +105,20 @@ CREATE SERVER <replaceable class="parameter">servername</replaceable> [ TYPE 'se
   </variablelist>
  </refsect1>
 
+ <refsect1>
+  <title>Notes</title>
+
+  <para>
+   When using the <application>dblink</application> module
+   (see <xref linkend="dblink">), the foreign server 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
+   the <literal>USAGE</literal> privilege on the foreign server to be
+   able to use it in this way.
+  </para>
+ </refsect1>
+
  <refsect1>
   <title>Examples</title>
 
diff --git a/doc/src/sgml/ref/create_user_mapping.sgml b/doc/src/sgml/ref/create_user_mapping.sgml
index 6d40eaf936..ab7ff7fdb1 100644
--- a/doc/src/sgml/ref/create_user_mapping.sgml
+++ b/doc/src/sgml/ref/create_user_mapping.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_user_mapping.sgml,v 1.4 2009/02/27 07:20:00 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_user_mapping.sgml,v 1.5 2009/06/18 14:34:36 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -31,7 +31,10 @@ CREATE USER MAPPING FOR { <replaceable class="parameter">username</replaceable>
 
   <para>
    <command>CREATE USER MAPPING</command> defines a mapping of a user
-   to a foreign server.
+   to a foreign server.  A user mapping typically encapsulates
+   connection information that a foreign-data wrapper uses together
+   with the information encapsulated be a foreign server to access an
+   external data resource.
   </para>
 
   <para>
@@ -52,8 +55,9 @@ CREATE USER MAPPING FOR { <replaceable class="parameter">username</replaceable>
      <para>
       The name of an existing user that is mapped to foreign server.
       <literal>CURRENT_USER</> and <literal>USER</> match the name of
-      the current user.  <literal>PUBLIC</> is used to match all
-      present and future user names in the system.
+      the current user.  When <literal>PUBLIC</> is specified, a
+      so-called public mapping is created that is used when no
+      user-specific mapping is applicable.
      </para>
     </listitem>
    </varlistentry>