<!-- $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>

<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>

-- 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');

<!--

$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

-->

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>

<!--

$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

-->

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>

</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>

<!--

$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

-->

<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>

<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>