From 02c4e3533926f4e7398611b6349d7c438b86c63b Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sat, 25 Sep 2021 10:53:54 -0400
Subject: [PATCH] Doc: extend warnings about collation-mismatch hazards in
 postgres_fdw.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Be a little more vocal about the risks of remote collations not
matching local ones.  Actually fixing these risks seems hard,
and I've given up on the idea that it might be back-patchable.
So the best we can do for the back branches is add documentation.

Per discussion of bug #16583 from Jiří Fejfar.

Discussion: https://postgr.es/m/2438715.1632510693@sss.pgh.pa.us
---
 doc/src/sgml/postgres-fdw.sgml | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index cf7488ffb2..c1daf12770 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -95,8 +95,8 @@
   referenced columns of the remote table.  Although <filename>postgres_fdw</filename>
   is currently rather forgiving about performing data type conversions at
   need, surprising semantic anomalies may arise when types or collations do
-  not match, due to the remote server interpreting <literal>WHERE</literal> clauses
-  slightly differently from the local server.
+  not match, due to the remote server interpreting query conditions
+  differently from the local server.
  </para>
 
  <para>
@@ -537,6 +537,17 @@ OPTIONS (ADD password_required 'false');
        need to turn this off if the remote server has a different set of
        collation names than the local server does, which is likely to be the
        case if it's running on a different operating system.
+       If you do so, however, there is a very severe risk that the imported
+       table columns' collations will not match the underlying data, resulting
+       in anomalous query behavior.
+      </para>
+
+      <para>
+       Even when this parameter is set to <literal>true</literal>, importing
+       columns whose collation is the remote server's default can be risky.
+       They will be imported with <literal>COLLATE "default"</literal>, which
+       will select the local server's default collation, which could be
+       different.
       </para>
      </listitem>
     </varlistentry>
@@ -614,9 +625,9 @@ OPTIONS (ADD password_required 'false');
      establishes to foreign servers are kept open in the local session
      for re-use.
     </para>
- 
+
     <variablelist>
- 
+
      <varlistentry>
       <term><literal>keep_connections</literal></term>
       <listitem>
@@ -630,7 +641,7 @@ OPTIONS (ADD password_required 'false');
       </para>
       </listitem>
      </varlistentry>
- 
+
     </variablelist>
    </sect3>
  </sect2>