From 522400a5198f63823406202e18fdaf3621619d98 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sat, 15 Aug 2015 14:31:04 -0400
Subject: [PATCH] Add docs about postgres_fdw's setting of search_path and
 other GUCs.

This behavior wasn't documented, but it should be because it's user-visible
in triggers and other functions executed on the remote server.
Per question from Adam Fuchs.

Back-patch to 9.3 where postgres_fdw was added.
---
 doc/src/sgml/postgres-fdw.sgml | 35 ++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 14b12e37dc..7c922821e9 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -437,6 +437,41 @@
   </para>
  </sect2>
 
+ <sect2>
+  <title>Remote Query Execution Environment</title>
+
+  <para>
+   In the remote sessions opened by <filename>postgres_fdw</>,
+   the <xref linkend="guc-search-path"> parameter is set to
+   just <literal>pg_catalog</>, so that only built-in objects are visible
+   without schema qualification.  This is not an issue for queries
+   generated by <filename>postgres_fdw</> itself, because it always
+   supplies such qualification.  However, this can pose a hazard for
+   functions that are executed on the remote server via triggers or rules
+   on remote tables.  For example, if a remote table is actually a view,
+   any functions used in that view will be executed with the restricted
+   search path.  It is recommended to schema-qualify all names in such
+   functions, or else attach <literal>SET search_path</> options
+   (see <xref linkend="sql-createfunction">) to such functions
+   to establish their expected search path environment.
+  </para>
+
+  <para>
+   <filename>postgres_fdw</> likewise establishes remote session settings
+   for the parameters <xref linkend="guc-timezone">,
+   <xref linkend="guc-datestyle">, <xref linkend="guc-intervalstyle">,
+   and <xref linkend="guc-extra-float-digits">.  These are less likely
+   to be problematic than <varname>search_path</>, but can be handled
+   with function <literal>SET</> options if the need arises.
+  </para>
+
+  <para>
+   It is <emphasis>not</> recommended that you override this behavior by
+   changing the session-level settings of these parameters; that is likely
+   to cause <filename>postgres_fdw</> to malfunction.
+  </para>
+ </sect2>
+
  <sect2>
   <title>Cross-Version Compatibility</title>