doc/src/sgml/ref/create_foreign_data_wrapper.sgml

   1 <!--
   2 $PostgreSQL$
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-CREATEFOREIGNDATAWRAPPER">
   7  <refmeta>
   8   <refentrytitle id="sql-createforeigndatawrapper-title">CREATE FOREIGN DATA WRAPPER</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>CREATE FOREIGN DATA WRAPPER</refname>
  15   <refpurpose>define a new foreign-data wrapper</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="sql-createforeigndatawrapper">
  19   <primary>CREATE FOREIGN DATA WRAPPER</primary>
  20  </indexterm>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
  25     [ VALIDATOR <replaceable class="parameter">valfunction</replaceable> | NO VALIDATOR ]
  26     [ OPTIONS ( <replaceable class="PARAMETER">option</replaceable> '<replaceable class="PARAMETER">value</replaceable>' [, ... ] ) ]
  27 </synopsis>
  28  </refsynopsisdiv>
  29
  30  <refsect1>
  31   <title>Description</title>
  32
  33   <para>
  34    <command>CREATE FOREIGN DATA WRAPPER</command> creates a new
  35    foreign-data wrapper.  The user who defines a foreign-data wrapper
  36    becomes its owner.
  37   </para>
  38
  39   <para>
  40    The foreign-data wrapper name must be unique within the database.
  41   </para>
  42
  43   <para>
  44    Only superusers can create foreign-data wrappers.
  45   </para>
  46  </refsect1>
  47
  48  <refsect1>
  49   <title>Parameters</title>
  50
  51   <variablelist>
  52    <varlistentry>
  53     <term><replaceable class="parameter">name</replaceable></term>
  54     <listitem>
  55      <para>
  56       The name of the foreign-data wrapper to be created.
  57      </para>
  58     </listitem>
  59    </varlistentry>
  60
  61    <varlistentry>
  62     <term><literal>VALIDATOR <replaceable class="parameter">valfunction</replaceable></literal></term>
  63     <listitem>
  64      <para>
  65       <replaceable class="parameter">valfunction</replaceable> is the
  66       name of a previously registered function that will be called to
  67       check the generic options given to the foreign-data wrapper, as
  68       well as to foreign servers and user mappings using the
  69       foreign-data wrapper.  If no validator function or <literal>NO
  70       VALIDATOR</literal> is specified, then options will not be
  71       checked at creation time.  (Foreign-data wrappers will possibly
  72       ignore or reject invalid option specifications at run time,
  73       depending on the implementation.)  The validator function must
  74       take two arguments: one of type <type>text[]</type>, which will
  75       contain the array of options as stored in the system catalogs,
  76       and one of type <type>oid</type>, which will be the OID of the
  77       system catalog containing the options, or zero if the context is
  78       not known.  The return type is ignored; the function should
  79       indicate invalid options using
  80       the <function>ereport()</function> function.
  81      </para>
  82     </listitem>
  83    </varlistentry>
  84
  85    <varlistentry>
  86     <term><literal>OPTIONS ( <replaceable class="PARAMETER">option</replaceable> '<replaceable class="PARAMETER">value</replaceable>' [, ... ] )</literal></term>
  87     <listitem>
  88      <para>
  89       This clause specifies options for the new foreign-data wrapper.
  90       The allowed option names and values are specific to each foreign
  91       data wrapper and are validated using the foreign-data wrapper
  92       library.  Option names must be unique.
  93      </para>
  94     </listitem>
  95    </varlistentry>
  96   </variablelist>
  97  </refsect1>
  98
  99  <refsect1>
 100   <title>Notes</title>
 101
 102   <para>
 103    At the moment, the foreign-data wrapper functionality is very
 104    rudimentary.  The purpose of foreign-data wrappers, foreign
 105    servers, and user mappings is to store this information in a
 106    standard way so that it can be queried by interested applications.
 107    One such application is <application>dblink</application>;
 108    see <xref linkend="dblink">.  The functionality to actually query
 109    external data through a foreign-data wrapper library does not exist
 110    yet.
 111   </para>
 112
 113   <para>
 114    There is currently one foreign-data wrapper validator function
 115    provided:
 116    <filename>postgresql_fdw_validator</filename>, which accepts
 117    options corresponding to <application>libpq</> connection
 118    parameters.
 119   </para>
 120  </refsect1>
 121
 122  <refsect1>
 123   <title>Examples</title>
 124
 125   <para>
 126    Create a foreign-data wrapper <literal>dummy</>:
 127 <programlisting>
 128 CREATE FOREIGN DATA WRAPPER dummy;
 129 </programlisting>
 130   </para>
 131
 132   <para>
 133    Create a foreign-data wrapper <literal>postgresql</> with
 134    validator function <literal>postgresql_fdw_validator</>:
 135 <programlisting>
 136 CREATE FOREIGN DATA WRAPPER postgresql VALIDATOR postgresql_fdw_validator;
 137 </programlisting>
 138   </para>
 139
 140   <para>
 141    Create a foreign-data wrapper <literal>mywrapper</> with some
 142    options:
 143 <programlisting>
 144 CREATE FOREIGN DATA WRAPPER mywrapper
 145     OPTIONS (debug 'true');
 146 </programlisting>
 147   </para>
 148  </refsect1>
 149
 150  <refsect1>
 151   <title>Compatibility</title>
 152
 153   <para>
 154    <command>CREATE FOREIGN DATA WRAPPER</command> conforms to ISO/IEC
 155    9075-9 (SQL/MED), with the exception that
 156    the <literal>VALIDATOR</literal> clause is an extension and the
 157    clauses <literal>LIBRARY</literal> and <literal>LANGUAGE</literal>
 158    are not yet implemented in PostgreSQL.
 159   </para>
 160
 161   <para>
 162    Note, however, that the SQL/MED functionality as a whole is not yet
 163    conforming.
 164   </para>
 165  </refsect1>
 166
 167  <refsect1>
 168   <title>See Also</title>
 169
 170   <simplelist type="inline">
 171    <member><xref linkend="sql-alterforeigndatawrapper" endterm="sql-alterforeigndatawrapper-title"></member>
 172    <member><xref linkend="sql-dropforeigndatawrapper" endterm="sql-dropforeigndatawrapper-title"></member>
 173    <member><xref linkend="sql-createserver" endterm="sql-createserver-title"></member>
 174    <member><xref linkend="sql-createusermapping" endterm="sql-createusermapping-title"></member>
 175   </simplelist>
 176  </refsect1>
 177
 178 </refentry>