Remove duplicated part of postgresql_fdw document.

diff --git a/doc/src/sgml/postgresql-fdw.sgml b/doc/src/sgml/postgresql-fdw.sgml
index 139ea9baa27ca2735fe3cd4d7ab403837d1ca44b..fc25e77a1c67e86fda9cdfc8271e408ad24dda6e 100644 (file)
--- a/doc/src/sgml/postgresql-fdw.sgml
+++ b/doc/src/sgml/postgresql-fdw.sgml
@@ -33,9 +33,7 @@
      <para>
       Internally, it returns a pointer to a <structname>FdwRoutine</structname>
       object which has set of foreign-data wrapper API functions for handling
-      foreign scan on the external PostgreSQL server.  Functions other than
-      Iterate can be NULL if the foreign-data wrapper has nothing to do in the
-      function.
+      foreign scan on the external PostgreSQL server.
      </para>
     </listitem>
    </varlistentry>
@@ -63,10 +61,10 @@
   <sect3>
    <title>Connection management</title>
    <para>
-    The postgresql_fdw connects to a remote PostgreSQL server when
-    <function>pgConnectServer()</function> is called for the foreign server
-    first time in the local query.  The connection is used by all of remote
-    queries which are executed on same remote PostgreSQL server.
+    The postgresql_fdw connects to a remote PostgreSQL server when a scan on
+    the server is requested first time in the local query.
+    The connection is used by all of remote queries which are executed on same
+    remote PostgreSQL server.
     If the local query uses multiple foreign PostgreSQL servers, connections
     are established for each server (not for each foreign table) and all of
     them will be closed at the end of the query.  This also means that
@@ -131,7 +129,7 @@
        <entry></entry>
       </row>
       <row>
-       <entry>Immutable operator</entry>
+       <entry>Non-volatile operator</entry>
        <entry></entry>
       </row>
       <row>
@@ -145,643 +143,7 @@
        <entry></entry>
       </row>
       <row>
-       <entry>Immutable function call</entry>
-       <entry></entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </table>
-
-  </sect3>
-
- </sect2>
-
-</sect1>
-<!-- doc/src/sgml/postgresql_fdw.sgml -->
-
-<sect1 id="postgresql-fdw">
- <title>postgresql_fdw</title>
-
- <indexterm zone="postgresql-fdw">
-  <primary>postgresql_fdw</primary>
- </indexterm>
-
- <para>
-  The <filename>postgresql_fdw</> module provides foreign-data wrapper
-  handler function <function>postgresql_fdw_handler</function> which can be
-  used to access external <productname>PostgreSQL</> server via plain SQL.
- </para>
-
- <sect2>
-  <title>Functions</title>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <function>postgresql_fdw_handler() returns fdw_handler</function>
-    </term>
-
-    <listitem>
-     <para>
-      <function>postgresql_fdw_handler</function> is a foreign-data wrapper
-      handler function which returns foreign-data wrapper handler for
-      PostgreSQL in type of <type>fdw_handler</type>.
-      Since fdw_hanlder is a pseudo type, postgresql_fdw_handler can't be
-      called from a SQL statement.
-     </para>
-     <para>
-      Internally, it returns a pointer to a <structname>FdwRoutine</structname>
-      object which has set of foreign-data wrapper API functions for handling
-      foreign scan on the external PostgreSQL server.  Functions other than
-      Iterate can be NULL if the foreign-data wrapper has nothing to do in the
-      function.
-     </para>
-    </listitem>
-   </varlistentry>
-
-  </variablelist>
-
- </sect2>
-
- <sect2>
-  <title>Details of postgresql_fdw</title>
-
-  <sect3>
-   <title>Connection options</title>
-   <para>
-    The postgresql_fdw retrieves connection information from generic options of
-    user mapping and foriegn server.  All of generic options of these objects
-    are passed to <function>PQconnectdbParams()</function>.
-   </para>
-   <para>
-    Currently, all of the generic options which are allowed in the context of
-    user mapping and foreign server are libpq connection options.
-   </para>
-  </sect3>
-
-  <sect3>
-   <title>Connection management</title>
-   <para>
-    The postgresql_fdw connects to a remote PostgreSQL server when
-    <function>pgConnectServer()</function> is called for the foreign server
-    first time in the local query.  The connection is used by all of remote
-    queries which are executed on same remote PostgreSQL server.
-    If the local query uses multiple foreign PostgreSQL servers, connections
-    are established for each server (not for each foreign table) and all of
-    them will be closed at the end of the query.  This also means that
-    connection pooling is not implemented in postgresql_fdw.
-   </para>
-   <para>
-   </para>
-  </sect3>
-
-  <sect3>
-   <title>Transaction management</title>
-   <para>
-    The postgresql_fdw never emit transaction command such as <command>BEGIN</>,
-    <command>ROLLBACK</> and <command>COMMIT</>. Thus, all SQL statements are
-    executed in each transaction when '<varname>autocommit</>' was set to 'on'. 
-   </para>
-  </sect3>
-
-  <sect3>
-   <title>Retrieving all tuples at once</title>
-   <para>
-    The postgresql_fdw retrieves all of the result tuples at once via libpq
-    when the query was executed.  Note that huge result set causes huge memory
-    consumption.  The memory for the result set will be freed at the end of the
-    each query.
-   </para>
-  </sect3>
-
-  <sect3>
-   <title>WHERE clause push-down</title>
-   <para>
-    The postgresql_fdw pushes some part of WHERE clause down to the remote
-    server, only if the evaluating the part of clause doesn't break the
-    consistency of the query.  If a clause consist of elements below, the
-    clause will be pushed down.
-   </para>
-   <table id="postgresql-fdw-push-downable">
-    <title>push-down-able elements</title>
-    <tgroup cols="2">
-     <thead>
-      <row>
-      <entry>Element</entry>
-       <entry>Note</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>Constant value and column reference</entry>
-      <entry></entry>
-      </row>
-      <row>
-       <entry>Array of push-down-able type</entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Parameter of <command>EXECUTE</command></entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Bool expression such as <literal>A AND B</literal> or
-       <literal>A OR B</literal></entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Immutable operator</entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>DISTINCT operator, such as
-       <literal>A IS DISTINCT FROM B</literal></entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Scalar array operator, such as <literal>ALL(...)</literal> and
-       <literal>ANY(...)</literal></entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Immutable function call</entry>
-       <entry></entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </table>
-
-  </sect3>
-
- </sect2>
-
-</sect1>
-<!-- doc/src/sgml/postgresql_fdw.sgml -->
-
-<sect1 id="postgresql-fdw">
- <title>postgresql_fdw</title>
-
- <indexterm zone="postgresql-fdw">
-  <primary>postgresql_fdw</primary>
- </indexterm>
-
- <para>
-  The <filename>postgresql_fdw</> module provides foreign-data wrapper
-  handler function <function>postgresql_fdw_handler</function> which can be
-  used to access external <productname>PostgreSQL</> server via plain SQL.
- </para>
-
- <sect2>
-  <title>Functions</title>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <function>postgresql_fdw_handler() returns fdw_handler</function>
-    </term>
-
-    <listitem>
-     <para>
-      <function>postgresql_fdw_handler</function> is a foreign-data wrapper
-      handler function which returns foreign-data wrapper handler for
-      PostgreSQL in type of <type>fdw_handler</type>.
-      Since fdw_hanlder is a pseudo type, postgresql_fdw_handler can't be
-      called from a SQL statement.
-     </para>
-     <para>
-      Internally, it returns a pointer to a <structname>FdwRoutine</structname>
-      object which has set of foreign-data wrapper API functions for handling
-      foreign scan on the external PostgreSQL server.  Functions other than
-      Iterate can be NULL if the foreign-data wrapper has nothing to do in the
-      function.
-     </para>
-    </listitem>
-   </varlistentry>
-
-  </variablelist>
-
- </sect2>
-
- <sect2>
-  <title>Details of postgresql_fdw</title>
-
-  <sect3>
-   <title>Connection options</title>
-   <para>
-    The postgresql_fdw retrieves connection information from generic options of
-    user mapping and foriegn server.  All of generic options of these objects
-    are passed to <function>PQconnectdbParams()</function>.
-   </para>
-   <para>
-    Currently, all of the generic options which are allowed in the context of
-    user mapping and foreign server are libpq connection options.
-   </para>
-  </sect3>
-
-  <sect3>
-   <title>Connection management</title>
-   <para>
-    The postgresql_fdw connects to a remote PostgreSQL server when
-    <function>pgConnectServer()</function> is called for the foreign server
-    first time in the local query.  The connection is used by all of remote
-    queries which are executed on same remote PostgreSQL server.
-    If the local query uses multiple foreign PostgreSQL servers, connections
-    are established for each server (not for each foreign table) and all of
-    them will be closed at the end of the query.  This also means that
-    connection pooling is not implemented in postgresql_fdw.
-   </para>
-   <para>
-   </para>
-  </sect3>
-
-  <sect3>
-   <title>Transaction management</title>
-   <para>
-    The postgresql_fdw never emit transaction command such as <command>BEGIN</>,
-    <command>ROLLBACK</> and <command>COMMIT</>. Thus, all SQL statements are
-    executed in each transaction when '<varname>autocommit</>' was set to 'on'. 
-   </para>
-  </sect3>
-
-  <sect3>
-   <title>Retrieving all tuples at once</title>
-   <para>
-    The postgresql_fdw retrieves all of the result tuples at once via libpq
-    when the query was executed.  Note that huge result set causes huge memory
-    consumption.  The memory for the result set will be freed at the end of the
-    each query.
-   </para>
-  </sect3>
-
-  <sect3>
-   <title>WHERE clause push-down</title>
-   <para>
-    The postgresql_fdw pushes some part of WHERE clause down to the remote
-    server, only if the evaluating the part of clause doesn't break the
-    consistency of the query.  If a clause consist of elements below, the
-    clause will be pushed down.
-   </para>
-   <table id="postgresql-fdw-push-downable">
-    <title>push-down-able elements</title>
-    <tgroup cols="2">
-     <thead>
-      <row>
-      <entry>Element</entry>
-       <entry>Note</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>Constant value and column reference</entry>
-      <entry></entry>
-      </row>
-      <row>
-       <entry>Array of push-down-able type</entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Parameter of <command>EXECUTE</command></entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Bool expression such as <literal>A AND B</literal> or
-       <literal>A OR B</literal></entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Immutable operator</entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>DISTINCT operator, such as
-       <literal>A IS DISTINCT FROM B</literal></entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Scalar array operator, such as <literal>ALL(...)</literal> and
-       <literal>ANY(...)</literal></entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Immutable function call</entry>
-       <entry></entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </table>
-
-  </sect3>
-
- </sect2>
-
-</sect1>
-<!-- doc/src/sgml/postgresql_fdw.sgml -->
-
-<sect1 id="postgresql-fdw">
- <title>postgresql_fdw</title>
-
- <indexterm zone="postgresql-fdw">
-  <primary>postgresql_fdw</primary>
- </indexterm>
-
- <para>
-  The <filename>postgresql_fdw</> module provides foreign-data wrapper
-  handler function <function>postgresql_fdw_handler</function> which can be
-  used to access external <productname>PostgreSQL</> server via plain SQL.
- </para>
-
- <sect2>
-  <title>Functions</title>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <function>postgresql_fdw_handler() returns fdw_handler</function>
-    </term>
-
-    <listitem>
-     <para>
-      <function>postgresql_fdw_handler</function> is a foreign-data wrapper
-      handler function which returns foreign-data wrapper handler for
-      PostgreSQL in type of <type>fdw_handler</type>.
-      Since fdw_hanlder is a pseudo type, postgresql_fdw_handler can't be
-      called from a SQL statement.
-     </para>
-     <para>
-      Internally, it returns a pointer to a <structname>FdwRoutine</structname>
-      object which has set of foreign-data wrapper API functions for handling
-      foreign scan on the external PostgreSQL server.  Functions other than
-      Iterate can be NULL if the foreign-data wrapper has nothing to do in the
-      function.
-     </para>
-    </listitem>
-   </varlistentry>
-
-  </variablelist>
-
- </sect2>
-
- <sect2>
-  <title>Details of postgresql_fdw</title>
-
-  <sect3>
-   <title>Connection options</title>
-   <para>
-    The postgresql_fdw retrieves connection information from generic options of
-    user mapping and foriegn server.  All of generic options of these objects
-    are passed to <function>PQconnectdbParams()</function>.
-   </para>
-   <para>
-    Currently, all of the generic options which are allowed in the context of
-    user mapping and foreign server are libpq connection options.
-   </para>
-  </sect3>
-
-  <sect3>
-   <title>Connection management</title>
-   <para>
-    The postgresql_fdw connects to a remote PostgreSQL server when
-    <function>pgConnectServer()</function> is called for the foreign server
-    first time in the local query.  The connection is used by all of remote
-    queries which are executed on same remote PostgreSQL server.
-    If the local query uses multiple foreign PostgreSQL servers, connections
-    are established for each server (not for each foreign table) and all of
-    them will be closed at the end of the query.  This also means that
-    connection pooling is not implemented in postgresql_fdw.
-   </para>
-   <para>
-   </para>
-  </sect3>
-
-  <sect3>
-   <title>Transaction management</title>
-   <para>
-    The postgresql_fdw never emit transaction command such as <command>BEGIN</>,
-    <command>ROLLBACK</> and <command>COMMIT</>. Thus, all SQL statements are
-    executed in each transaction when '<varname>autocommit</>' was set to 'on'. 
-   </para>
-  </sect3>
-
-  <sect3>
-   <title>Retrieving all tuples at once</title>
-   <para>
-    The postgresql_fdw retrieves all of the result tuples at once via libpq
-    when the query was executed.  Note that huge result set causes huge memory
-    consumption.  The memory for the result set will be freed at the end of the
-    each query.
-   </para>
-  </sect3>
-
-  <sect3>
-   <title>WHERE clause push-down</title>
-   <para>
-    The postgresql_fdw pushes some part of WHERE clause down to the remote
-    server, only if the evaluating the part of clause doesn't break the
-    consistency of the query.  If a clause consist of elements below, the
-    clause will be pushed down.
-   </para>
-   <table id="postgresql-fdw-push-downable">
-    <title>push-down-able elements</title>
-    <tgroup cols="2">
-     <thead>
-      <row>
-      <entry>Element</entry>
-       <entry>Note</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>Constant value and column reference</entry>
-      <entry></entry>
-      </row>
-      <row>
-       <entry>Array of push-down-able type</entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Parameter of <command>EXECUTE</command></entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Bool expression such as <literal>A AND B</literal> or
-       <literal>A OR B</literal></entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Immutable operator</entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>DISTINCT operator, such as
-       <literal>A IS DISTINCT FROM B</literal></entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Scalar array operator, such as <literal>ALL(...)</literal> and
-       <literal>ANY(...)</literal></entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Immutable function call</entry>
-       <entry></entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </table>
-
-  </sect3>
-
- </sect2>
-
-</sect1>
-<!-- doc/src/sgml/postgresql_fdw.sgml -->
-
-<sect1 id="postgresql-fdw">
- <title>postgresql_fdw</title>
-
- <indexterm zone="postgresql-fdw">
-  <primary>postgresql_fdw</primary>
- </indexterm>
-
- <para>
-  The <filename>postgresql_fdw</> module provides foreign-data wrapper
-  handler function <function>postgresql_fdw_handler</function> which can be
-  used to access external <productname>PostgreSQL</> server via plain SQL.
- </para>
-
- <sect2>
-  <title>Functions</title>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <function>postgresql_fdw_handler() returns fdw_handler</function>
-    </term>
-
-    <listitem>
-     <para>
-      <function>postgresql_fdw_handler</function> is a foreign-data wrapper
-      handler function which returns foreign-data wrapper handler for
-      PostgreSQL in type of <type>fdw_handler</type>.
-      Since fdw_hanlder is a pseudo type, postgresql_fdw_handler can't be
-      called from a SQL statement.
-     </para>
-     <para>
-      Internally, it returns a pointer to a <structname>FdwRoutine</structname>
-      object which has set of foreign-data wrapper API functions for handling
-      foreign scan on the external PostgreSQL server.  Functions other than
-      Iterate can be NULL if the foreign-data wrapper has nothing to do in the
-      function.
-     </para>
-    </listitem>
-   </varlistentry>
-
-  </variablelist>
-
- </sect2>
-
- <sect2>
-  <title>Details of postgresql_fdw</title>
-
-  <sect3>
-   <title>Connection options</title>
-   <para>
-    The postgresql_fdw retrieves connection information from generic options of
-    user mapping and foriegn server.  All of generic options of these objects
-    are passed to <function>PQconnectdbParams()</function>.
-   </para>
-   <para>
-    Currently, all of the generic options which are allowed in the context of
-    user mapping and foreign server are libpq connection options.
-   </para>
-  </sect3>
-
-  <sect3>
-   <title>Connection management</title>
-   <para>
-    The postgresql_fdw connects to a remote PostgreSQL server when
-    <function>pgConnectServer()</function> is called for the foreign server
-    first time in the local query.  The connection is used by all of remote
-    queries which are executed on same remote PostgreSQL server.
-    If the local query uses multiple foreign PostgreSQL servers, connections
-    are established for each server (not for each foreign table) and all of
-    them will be closed at the end of the query.  This also means that
-    connection pooling is not implemented in postgresql_fdw.
-   </para>
-   <para>
-   </para>
-  </sect3>
-
-  <sect3>
-   <title>Transaction management</title>
-   <para>
-    The postgresql_fdw never emit transaction command such as <command>BEGIN</>,
-    <command>ROLLBACK</> and <command>COMMIT</>. Thus, all SQL statements are
-    executed in each transaction when '<varname>autocommit</>' was set to 'on'. 
-   </para>
-  </sect3>
-
-  <sect3>
-   <title>Retrieving all tuples at once</title>
-   <para>
-    The postgresql_fdw retrieves all of the result tuples at once via libpq
-    when the query was executed.  Note that huge result set causes huge memory
-    consumption.  The memory for the result set will be freed at the end of the
-    each query.
-   </para>
-  </sect3>
-
-  <sect3>
-   <title>WHERE clause push-down</title>
-   <para>
-    The postgresql_fdw pushes some part of WHERE clause down to the remote
-    server, only if the evaluating the part of clause doesn't break the
-    consistency of the query.  If a clause consist of elements below, the
-    clause will be pushed down.
-   </para>
-   <table id="postgresql-fdw-push-downable">
-    <title>push-down-able elements</title>
-    <tgroup cols="2">
-     <thead>
-      <row>
-      <entry>Element</entry>
-       <entry>Note</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>Constant value and column reference</entry>
-      <entry></entry>
-      </row>
-      <row>
-       <entry>Array of push-down-able type</entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Parameter of <command>EXECUTE</command></entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Bool expression such as <literal>A AND B</literal> or
-       <literal>A OR B</literal></entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Immutable operator</entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>DISTINCT operator, such as
-       <literal>A IS DISTINCT FROM B</literal></entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Scalar array operator, such as <literal>ALL(...)</literal> and
-       <literal>ANY(...)</literal></entry>
-       <entry></entry>
-      </row>
-      <row>
-       <entry>Immutable function call</entry>
+       <entry>Non-volatile function call</entry>
        <entry></entry>
       </row>
      </tbody>