doc/src/sgml/ref/create_foreign_data_wrapper.sgml

<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/create_foreign_data_wrapper.sgml,v 1.5 2009/06/19 15:28:25 petere Exp $
PostgreSQL documentation
-->

<refentry id="SQL-CREATEFOREIGNDATAWRAPPER">
 <refmeta>
  <refentrytitle id="sql-createforeigndatawrapper-title">CREATE FOREIGN DATA WRAPPER</refentrytitle>
  <manvolnum>7</manvolnum>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CREATE FOREIGN DATA WRAPPER</refname>
  <refpurpose>define a new foreign-data wrapper</refpurpose>
 </refnamediv>

 <indexterm zone="sql-createforeigndatawrapper">
  <primary>CREATE FOREIGN DATA WRAPPER</primary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
    [ VALIDATOR <replaceable class="parameter">valfunction</replaceable> | NO VALIDATOR ]
    [ OPTIONS ( <replaceable class="PARAMETER">option</replaceable> '<replaceable class="PARAMETER">value</replaceable>' [, ... ] ) ]
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>CREATE FOREIGN DATA WRAPPER</command> creates a new
   foreign-data wrapper.  The user who defines a foreign-data wrapper
   becomes its owner.
  </para>

  <para>
   The foreign-data wrapper name must be unique within the database.
  </para>

  <para>
   Only superusers can create foreign-data wrappers.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

  <variablelist>
   <varlistentry>
    <term><replaceable class="parameter">name</replaceable></term>
    <listitem>
     <para>
      The name of the foreign-data wrapper to be created.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>VALIDATOR <replaceable class="parameter">valfunction</replaceable></literal></term>
    <listitem>
     <para>
      <replaceable class="parameter">valfunction</replaceable> is the
      name of a previously registered function that will be called to
      check the generic options given to the foreign-data wrapper, as
      well as to foreign servers and user mappings using the
      foreign-data wrapper.  If no validator function or <literal>NO
      VALIDATOR</literal> is specified, then options will not be
      checked at creation time.  (Foreign-data wrappers will possibly
      ignore or reject invalid option specifications at run time,
      depending on the implementation.)  The validator function must
      take two arguments: one of type <type>text[]</type>, which will
      contain the array of options as stored in the system catalogs,
      and one of type <type>oid</type>, which will be the OID of the
      system catalog containing the options, or zero if the context is
      not known.  The return type is ignored; the function should
      indicate invalid options using
      the <function>ereport()</function> function.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>OPTIONS ( <replaceable class="PARAMETER">option</replaceable> '<replaceable class="PARAMETER">value</replaceable>' [, ... ] )</literal></term>
    <listitem>
     <para>
      This clause specifies options for the new foreign-data wrapper.
      The allowed option names and values are specific to each foreign
      data wrapper and are validated using the foreign-data wrapper
      library.  Option names must be unique.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   At the moment, the foreign-data wrapper functionality is very
   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.
   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>

  <para>
   There is currently one foreign-data wrapper validator function
   provided:
   <filename>postgresql_fdw_validator</filename>, which accepts
   options corresponding to <application>libpq</> connection
   parameters.
  </para>
 </refsect1>

 <refsect1>
  <title>Examples</title>

  <para>
   Create a foreign-data wrapper <literal>dummy</>:
<programlisting>
CREATE FOREIGN DATA WRAPPER dummy;
</programlisting>
  </para>

  <para>
   Create a foreign-data wrapper <literal>postgresql</> with
   validator function <literal>postgresql_fdw_validator</>:
<programlisting>
CREATE FOREIGN DATA WRAPPER postgresql VALIDATOR postgresql_fdw_validator;
</programlisting>
  </para>

  <para>
   Create a foreign-data wrapper <literal>mywrapper</> with some
   options:
<programlisting>
CREATE FOREIGN DATA WRAPPER mywrapper
    OPTIONS (debug 'true');
</programlisting>
  </para>
 </refsect1>

 <refsect1>
  <title>Compatibility</title>

  <para>
   <command>CREATE FOREIGN DATA WRAPPER</command> conforms to ISO/IEC
   9075-9 (SQL/MED), with the exception that
   the <literal>VALIDATOR</literal> clause is an extension and the
   clauses <literal>LIBRARY</literal> and <literal>LANGUAGE</literal>
   are not yet implemented in PostgreSQL.
  </para>

  <para>
   Note, however, that the SQL/MED functionality as a whole is not yet
   conforming.
  </para>
 </refsect1>

 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="sql-alterforeigndatawrapper" endterm="sql-alterforeigndatawrapper-title"></member>
   <member><xref linkend="sql-dropforeigndatawrapper" endterm="sql-dropforeigndatawrapper-title"></member>
   <member><xref linkend="sql-createserver" endterm="sql-createserver-title"></member>
   <member><xref linkend="sql-createusermapping" endterm="sql-createusermapping-title"></member>
  </simplelist>
 </refsect1>

</refentry>