<!--
doc/src/sgml/ref/create_user_mapping.sgml
PostgreSQL documentation
-->

<refentry id="sql-createusermapping">
 <indexterm zone="sql-createusermapping">
  <primary>CREATE USER MAPPING</primary>
 </indexterm>

 <refmeta>
  <refentrytitle>CREATE USER MAPPING</refentrytitle>
  <manvolnum>7</manvolnum>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CREATE USER MAPPING</refname>
  <refpurpose>define a new mapping of a user to a foreign server</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
CREATE USER MAPPING [ IF NOT EXISTS ] FOR { <replaceable class="parameter">user_name</replaceable> | USER | CURRENT_ROLE | CURRENT_USER | PUBLIC }
    SERVER <replaceable class="parameter">server_name</replaceable>
    [ OPTIONS ( <replaceable class="parameter">option</replaceable> '<replaceable class="parameter">value</replaceable>' [ , ... ] ) ]
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>CREATE USER MAPPING</command> defines a mapping of a user
   to a foreign server.  A user mapping typically encapsulates
   connection information that a foreign-data wrapper uses together
   with the information encapsulated by a foreign server to access an
   external data resource.
  </para>

  <para>
   The owner of a foreign server can create user mappings for that
   server for any user.  Also, a user can create a user mapping for
   their own user name if <literal>USAGE</literal> privilege on the server has
   been granted to the user.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

  <variablelist>
  <varlistentry>
    <term><literal>IF NOT EXISTS</literal></term>
    <listitem>
     <para>
      Do not throw an error if a mapping of the given user to the given foreign
      server already exists. A notice is issued in this case.  Note that there
      is no guarantee that the existing user mapping is anything like the one
      that would have been created.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">user_name</replaceable></term>