diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml
index f050ff1f6601773cad9589f3f2715d2d822b3b54..df88380a23051152e050d749bb8130c6462221d3 100644
--- a/doc/src/sgml/extend.sgml
+++ b/doc/src/sgml/extend.sgml
@@ -335,11 +335,13 @@
by <application>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 <xref linkend="extend-extensions-config-tables">.)
+ In production situations, it's generally better to create an extension
+ update script to perform changes to extension member objects.
</para>
<para>
- 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 <command>GRANT</command> and <command>REVOKE</command>
statements. The final set of privileges for each object (if any are set)
will be stored in the
@@ -453,9 +455,11 @@
<term><varname>comment</varname> (<type>string</type>)</term>
<listitem>
<para>
- A comment (any string) about the extension. Alternatively,
- the comment can be set by means of the <xref linkend="sql-comment">
- 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 <xref linkend="sql-comment"> command in the script file.
</para>
</listitem>
</varlistentry>
@@ -518,7 +522,7 @@
its contained objects into a different schema after initial creation
of the extension. The default is <literal>false</>, i.e. the
extension is not relocatable.
- See below for more information.
+ See <xref linkend="extend-extensions-relocation"> for more information.
</para>
</listitem>
</varlistentry>
@@ -529,7 +533,10 @@
<para>
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 <varname>schema</varname> parameter is consulted only when
+ initially creating an extension, not during extension updates.
+ See <xref linkend="extend-extensions-relocation"> for more information.
</para>
</listitem>
</varlistentry>
@@ -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 <application>psql</>
rather than being loaded via <command>CREATE EXTENSION</> (see example
- script below). Without that, users might accidentally load the
+ script in <xref linkend="extend-extensions-example">).
+ Without that, users might accidentally load the
extension's contents as <quote>loose</> objects rather than as an
extension, a state of affairs that's a bit tedious to recover from.
</para>
@@ -580,7 +588,7 @@
</sect2>
- <sect2>
+ <sect2 id="extend-extensions-relocation">
<title>Extension Relocatability</title>
<para>
@@ -678,7 +686,7 @@ SET LOCAL search_path TO @extschema@;
</para>
</sect2>
- <sect2>
+ <sect2 id="extend-extensions-config-tables">
<title>Extension Configuration Tables</title>
<para>
@@ -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.
</para>
-
+
<para>
Sequences associated with <type>serial</> or <type>bigserial</> columns
need to be directly marked to dump their state. Marking their parent
@@ -877,7 +885,7 @@ SELECT * FROM pg_extension_update_paths('<replaceable>extension_name</>');
</para>
</sect2>
- <sect2>
+ <sect2 id="extend-extensions-example">
<title>Extension Example</title>
<para>
diff --git a/doc/src/sgml/ref/create_extension.sgml b/doc/src/sgml/ref/create_extension.sgml
index 007d8c9330626c4f15fb9b527907144a758f25b4..14e910115ab0564047b06ff93ed3cedabad7e01b 100644
--- 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 ] <replaceable class="parameter">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.
</para>
+
<para>
- If the extension specifies <literal>schema</> in its control file,
- the schema cannot be overridden with <literal>SCHEMA</> clause.
- The <literal>SCHEMA</> clause in this case works as follows:
- <itemizedlist>
- <listitem>
- <para>
- If <replaceable class="parameter">schema_name</replaceable> matches
- the schema in control file, it will be used normally as there is no
- conflict.
- </para>
- </listitem>
- <listitem>
- <para>
- If the <literal>CASCADE</> clause is given, the
- <replaceable class="parameter">schema_name</replaceable> will only
- be used for the missing required extensions which do not specify
- <literal>schema</> in their control files.
- </para>
- </listitem>
- <listitem>
- <para>
- If <replaceable class="parameter">schema_name</replaceable> is not
- the same as the one in extension's control file and the
- <literal>CASCADE</> clause is not given, error will be thrown.
- </para>
- </listitem>
- </itemizedlist>
+ If the extension specifies a <literal>schema</> parameter in its
+ control file, then that schema cannot be overridden with
+ a <literal>SCHEMA</> clause. Normally, an error will be raised if
+ a <literal>SCHEMA</> clause is given and it conflicts with the
+ extension's <literal>schema</> parameter. However, if
+ the <literal>CASCADE</> clause is also given,
+ then <replaceable class="parameter">schema_name</replaceable> is
+ ignored when it conflicts. The
+ given <replaceable class="parameter">schema_name</replaceable> will be
+ used for installation of any needed extensions that do not
+ specify <literal>schema</> in their control files.
</para>
+
<para>
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 ] <replaceable class="parameter">extension_name
<varlistentry>
<term><replaceable class="parameter">old_version</replaceable></term>
<listitem>
- <para><literal>FROM</> <replaceable class="parameter">old_version</>
+ <para>
+ <literal>FROM</> <replaceable class="parameter">old_version</>
must be specified when, and only when, you are attempting to install
an extension that replaces an <quote>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 ] <replaceable class="parameter">extension_name
<term><literal>CASCADE</></term>
<listitem>
<para>
- Try to install extension including the required dependencies
- recursively. The <literal>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 <literal>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.
</para>
</listitem>
</varlistentry>