pg_upgrade: improve docs about extension upgrades

The previous wording was unclear about the steps needed to upgrade
extensions, and how to update them after pg_upgrade.

Reported-by: Dave Cramer
Discussion: https://postgr.es/m/CADK3HHKawwbOcGwMGnDuAf3-U8YfvTcS8jqDv3UM=niijs3MMA@mail.gmail.com

Backpatch-through: 9.6

diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index a83c63cd98f4b6f716b3246bcf5cde0b644b3083..0a7146580506b46b1a9e395d52ff060d0cd8b391 100644 (file)
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -299,17 +299,27 @@ make prefix=/usr/local/pgsql.new install
    
 
    
-    Install <span class="marked">custom</span> shared object files
+    Install <span class="marked">extension</span> shared object files
 
     
-     Install any custom shared object files (or DLLs) used by the old cluster
-     into the new cluster, e.g., pgcrypto.so,
-     whether they are from contrib
-     or some other source. Do not install the schema definitions, e.g.,
-     CREATE EXTENSION pgcrypto, because these will be upgraded
-     from the old cluster.
-     Also, any custom full text search files (dictionary, synonym,
-     thesaurus, stop words) must also be copied to the new cluster.
+     Many extensions and custom modules, whether from
+     contrib or another source, use shared object
+     files (or DLLs), e.g., pgcrypto.so.  If the old
+     cluster used these, shared object files matching the new server binary
+     must be installed in the new cluster, usually via operating system
+     commands.  Do not load the schema definitions, e.g., CREATE
+     EXTENSION pgcrypto, because these will be duplicated from
+     the old cluster.  (Extensions with available updates can be processed
+     later using ALTER EXTENSION ... UPDATE.)
+    
+   
+
+   
+    Copy custom full-text search files
+
+    
+     Copy any custom full text search files (dictionary, synonym,
+     thesaurus, stop words) from the old to the new cluster.
     
    
 
@@ -494,10 +504,10 @@ pg_upgrade.exe
      
 
      
-      Install <span class="marked">custom</span> shared object files
+      Install <span class="marked">extension</span> shared object files
 
       
-       Install the same custom shared object files on the new standbys
+       Install the same extension shared object files on the new standbys
        that you installed in the new primary cluster.