doc/src/sgml/ref/import_foreign_schema.sgml

   1 <!--
   2 doc/src/sgml/ref/import_foreign_schema.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="sql-importforeignschema">
   7  <indexterm zone="sql-importforeignschema">
   8   <primary>IMPORT FOREIGN SCHEMA</primary>
   9  </indexterm>
  10
  11  <refmeta>
  12   <refentrytitle>IMPORT FOREIGN SCHEMA</refentrytitle>
  13   <manvolnum>7</manvolnum>
  14   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  15  </refmeta>
  16
  17  <refnamediv>
  18   <refname>IMPORT FOREIGN SCHEMA</refname>
  19   <refpurpose>import table definitions from a foreign server</refpurpose>
  20  </refnamediv>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 IMPORT FOREIGN SCHEMA <replaceable class="parameter">remote_schema</replaceable>
  25     [ { LIMIT TO | EXCEPT } ( <replaceable class="parameter">table_name</replaceable> [, ...] ) ]
  26     FROM SERVER <replaceable class="parameter">server_name</replaceable>
  27     INTO <replaceable class="parameter">local_schema</replaceable>
  28     [ OPTIONS ( <replaceable class="parameter">option</replaceable> '<replaceable class="parameter">value</replaceable>' [, ... ] ) ]
  29 </synopsis>
  30  </refsynopsisdiv>
  31
  32  <refsect1 id="sql-importforeignschema-description">
  33   <title>Description</title>
  34
  35   <para>
  36    <command>IMPORT FOREIGN SCHEMA</command> creates foreign tables that
  37    represent tables existing on a foreign server.  The new foreign tables
  38    will be owned by the user issuing the command and are created with
  39    the correct column definitions and options to match the remote tables.
  40   </para>
  41
  42   <para>
  43    By default, all tables and views existing in a particular schema on the
  44    foreign server are imported.  Optionally, the list of tables can be limited
  45    to a specified subset, or specific tables can be excluded.  The new foreign
  46    tables are all created in the target schema, which must already exist.
  47   </para>
  48
  49   <para>
  50    To use <command>IMPORT FOREIGN SCHEMA</command>, the user must have
  51    <literal>USAGE</literal> privilege on the foreign server, as well as
  52    <literal>CREATE</literal> privilege on the target schema.
  53   </para>
  54  </refsect1>
  55
  56  <refsect1>
  57   <title>Parameters</title>
  58
  59   <variablelist>
  60
  61    <varlistentry>
  62     <term><replaceable class="parameter">remote_schema</replaceable></term>
  63     <listitem>
  64      <para>
  65       The remote schema to import from. The specific meaning of a remote schema
  66       depends on the foreign data wrapper in use.
  67      </para>
  68     </listitem>
  69    </varlistentry>
  70
  71    <varlistentry>
  72     <term><literal>LIMIT TO ( <replaceable class="parameter">table_name</replaceable> [, ...] )</literal></term>
  73     <listitem>
  74      <para>
  75       Import only foreign tables matching one of the given table names.
  76       Other tables existing in the foreign schema will be ignored.
  77      </para>
  78     </listitem>
  79    </varlistentry>
  80
  81    <varlistentry>
  82     <term><literal>EXCEPT ( <replaceable class="parameter">table_name</replaceable> [, ...] )</literal></term>
  83     <listitem>
  84      <para>
  85       Exclude specified foreign tables from the import.  All tables
  86       existing in the foreign schema will be imported except the
  87       ones listed here.
  88      </para>
  89     </listitem>
  90    </varlistentry>
  91
  92    <varlistentry>
  93     <term><replaceable class="parameter">server_name</replaceable></term>
  94     <listitem>
  95      <para>
  96       The foreign server to import from.
  97      </para>
  98     </listitem>
  99    </varlistentry>
 100
 101    <varlistentry>
 102     <term><replaceable class="parameter">local_schema</replaceable></term>
 103     <listitem>
 104      <para>
 105       The schema in which the imported foreign tables will be created.
 106      </para>
 107     </listitem>
 108    </varlistentry>
 109
 110    <varlistentry>
 111     <term><literal>OPTIONS ( <replaceable class="parameter">option</replaceable> '<replaceable class="parameter">value</replaceable>' [, ...] )</literal></term>
 112     <listitem>
 113      <para>
 114       Options to be used during the import.
 115       The allowed option names and values are specific to each foreign
 116       data wrapper.
 117      </para>
 118     </listitem>
 119    </varlistentry>
 120   </variablelist>
 121  </refsect1>
 122
 123  <refsect1 id="sql-importforeignschema-examples">
 124   <title>Examples</title>
 125
 126   <para>
 127    Import table definitions from a remote schema <structname>foreign_films</structname>
 128    on server <structname>film_server</structname>, creating the foreign tables in
 129    local schema <structname>films</structname>:
 130
 131 <programlisting>
 132 IMPORT FOREIGN SCHEMA foreign_films
 133     FROM SERVER film_server INTO films;
 134 </programlisting>
 135    </para>
 136
 137   <para>
 138    As above, but import only the two tables <structname>actors</structname> and
 139    <literal>directors</literal> (if they exist):
 140
 141 <programlisting>
 142 IMPORT FOREIGN SCHEMA foreign_films LIMIT TO (actors, directors)
 143     FROM SERVER film_server INTO films;
 144 </programlisting></para>
 145  </refsect1>
 146
 147  <refsect1 id="sql-importforeignschema-compatibility">
 148   <title>Compatibility</title>
 149
 150   <para>
 151    The <command>IMPORT FOREIGN SCHEMA</command> command conforms to the
 152    <acronym>SQL</acronym> standard, except that the <literal>OPTIONS</literal>
 153    clause is a <productname>PostgreSQL</productname> extension.
 154   </para>
 155
 156  </refsect1>
 157
 158  <refsect1>
 159   <title>See Also</title>
 160
 161   <simplelist type="inline">
 162    <member><xref linkend="sql-createforeigntable"/></member>
 163    <member><xref linkend="sql-createserver"/></member>
 164   </simplelist>
 165  </refsect1>
 166 </refentry>