diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml
index 06fcc8cee8bfd7c32de384864e876db45490b0a9..2afa40a29f6efaba8ad7486652c7f3a9e19957a4 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 bc615476bdc14d63b56a26fe3e72d08fb821464e..dd48245372d18dc79f13b6e257a0dd7fc2635cf1 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 c588e6b3e6ab4aeed1118600afdcd3f1cb511cab..c828c5a28b62b5318ad3088ee241a58e93cb9f71 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 6d40eaf936b76cabebcb7abe73fdf64974692e47..ab7ff7fdb10717f43be6b08b391bae804bfa0920 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>