Doc: minor documentation improvements about extensions.

Document the formerly-undocumented behavior that schema and comment
control-file entries for an extension are honored only during initial
installation, whereas other properties are also honored during updates.

While at it, do some copy-editing on the recently-added docs for CREATE
EXTENSION ... CASCADE, use links for some formerly vague cross references,
and make a couple other minor improvements.

Back-patch to 9.6 where CASCADE was added.  The other parts of this
could go further back, but they're probably not important enough to
bother.

diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml
index f050ff1f6601773cad9589f3f2715d2d822b3b54..df88380a23051152e050d749bb8130c6462221d3 100644 (file)
--- a/doc/src/sgml/extend.sgml
+++ b/doc/src/sgml/extend.sgml
@@ -335,11 +335,13 @@
     by pg_dump.  Such a change is usually only sensible if
     you concurrently make the same change in the extension's script file.
     (But there are special provisions for tables containing configuration
-    data; see below.)
+    data; see .)
+    In production situations, it's generally better to create an extension
+    update script to perform changes to extension member objects.
    
 
    
-    The extension script may set privileges on objects which are part of the
+    The extension script may set privileges on objects that are part of the
     extension via GRANT and REVOKE
     statements.  The final set of privileges for each object (if any are set)
     will be stored in the
@@ -453,9 +455,11 @@
       comment (string)
       
        
-        A comment (any string) about the extension.  Alternatively,
-        the comment can be set by means of the 
-        command in the script file.
+        A comment (any string) about the extension.  The comment is applied
+        when initially creating an extension, but not during extension updates
+        (since that might override user-added comments).  Alternatively,
+        the extension's comment can be set by writing
+        a  command in the script file.
        
       
      
@@ -518,7 +522,7 @@
         its contained objects into a different schema after initial creation
         of the extension.  The default is false, i.e. the
         extension is not relocatable.
-        See below for more information.
+        See  for more information.
        
       
      
@@ -529,7 +533,10 @@
        
         This parameter can only be set for non-relocatable extensions.
         It forces the extension to be loaded into exactly the named schema
-        and not any other.  See below for more information.
+        and not any other.
+        The schema parameter is consulted only when
+        initially creating an extension, not during extension updates.
+        See  for more information.
        
       
      
@@ -562,7 +569,8 @@
      comments) by the extension mechanism.  This provision is commonly used
      to throw an error if the script file is fed to psql
      rather than being loaded via CREATE EXTENSION (see example
-     script below).  Without that, users might accidentally load the
+     script in ).
+     Without that, users might accidentally load the
      extension's contents as loose objects rather than as an
      extension, a state of affairs that's a bit tedious to recover from.
     
@@ -580,7 +588,7 @@
 
    
 
-   
+    id="extend-extensions-relocation">
     Extension Relocatability
 
     
@@ -678,7 +686,7 @@ SET LOCAL search_path TO @extschema@;
     
    
 
-   
+    id="extend-extensions-config-tables">
     Extension Configuration Tables
 
     
@@ -762,7 +770,7 @@ SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entr
      out but the dump will not be able to be restored directly and user
      intervention will be required.
     
-    
+
     
      Sequences associated with serial or bigserial columns
      need to be directly marked to dump their state. Marking their parent
@@ -877,7 +885,7 @@ SELECT * FROM pg_extension_update_paths('extension_name');
     
    
 
-   
+    id="extend-extensions-example">
     Extension Example
 
     

diff --git a/doc/src/sgml/ref/create_extension.sgml b/doc/src/sgml/ref/create_extension.sgml
index 007d8c9330626c4f15fb9b527907144a758f25b4..14e910115ab0564047b06ff93ed3cedabad7e01b 100644 (file)
--- a/doc/src/sgml/ref/create_extension.sgml
+++ b/doc/src/sgml/ref/create_extension.sgml
@@ -95,35 +95,21 @@ CREATE EXTENSION [ IF NOT EXISTS ] extension_name
         If not specified, and the extension's control file does not specify a
         schema either, the current default object creation schema is used.
        
+
        
-        If the extension specifies schema in its control file,
-        the schema cannot be overridden with SCHEMA clause.
-        The SCHEMA clause in this case works as follows:
-        
-         
-          
-           If schema_name matches
-           the schema in control file, it will be used normally as there is no
-           conflict.
-          
-         
-         
-          
-           If the CASCADE clause is given, the
-           schema_name will only
-           be used for the missing required extensions which do not specify
-           schema in their control files.
-          
-         
-         
-          
-           If schema_name is not
-           the same as the one in extension's control file and the
-           CASCADE clause is not given, error will be thrown.
-          
-         
-        
+        If the extension specifies a schema parameter in its
+        control file, then that schema cannot be overridden with
+        a SCHEMA clause.  Normally, an error will be raised if
+        a SCHEMA clause is given and it conflicts with the
+        extension's schema parameter.  However, if
+        the CASCADE clause is also given,
+        then schema_name is
+        ignored when it conflicts.  The
+        given schema_name will be
+        used for installation of any needed extensions that do not
+        specify schema in their control files.
        
+
        
         Remember that the extension itself is not considered to be within any
         schema: extensions have unqualified names that must be unique
@@ -147,7 +133,8 @@ CREATE EXTENSION [ IF NOT EXISTS ] extension_name
      
       old_version
       
-       FROM old_version
+       
+        FROM old_version
         must be specified when, and only when, you are attempting to install
         an extension that replaces an old style module that is just
         a collection of objects not packaged into an extension.  This option
@@ -174,10 +161,13 @@ CREATE EXTENSION [ IF NOT EXISTS ] extension_name
       CASCADE
       
        
-        Try to install extension including the required dependencies
-        recursively. The SCHEMA option will be propagated
-        to the required extensions.  Other options are not recursively
-        applied when using this clause.
+        Automatically install any extensions that this extension depends on
+        that are not already installed.  Their dependencies are likewise
+        automatically installed, recursively.  The SCHEMA clause,
+        if given, applies to all extensions that get installed this way.
+        Other options of the statement are not applied to
+        automatically-installed extensions; in particular, their default
+        versions are always selected.