Add CASCADE support for CREATE EXTENSION.

Without CASCADE, if an extension has an unfullfilled dependency on
another extension, CREATE EXTENSION ERRORs out with "required extension
... is not installed". That is annoying, especially when that dependency
is an implementation detail of the extension, rather than something the
extension's user can make sense of.

In addition to CASCADE this also includes a small set of regression
tests around CREATE EXTENSION.

Author: Petr Jelinek, editorialized by Michael Paquier, Andres Freund
Reviewed-By: Michael Paquier, Andres Freund, Jeff Janes
Discussion: 557E0520.3040800@2ndquadrant.com

1 files changed, 42 insertions, 0 deletions

diff --git a/doc/src/sgml/ref/create_extension.sgml b/doc/src/sgml/ref/create_extension.sgml
index a1e7e4f812c..d4cc310918e 100644
--- a/doc/src/sgml/ref/create_extension.sgml
+++ b/doc/src/sgml/ref/create_extension.sgml
@@ -25,6 +25,7 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name
     [ WITH ] [ SCHEMA <replaceable class="parameter">schema_name</replaceable> ]
              [ VERSION <replaceable class="parameter">version</replaceable> ]
              [ FROM <replaceable class="parameter">old_version</replaceable> ]
+             [ CASCADE ]
 </synopsis>
  </refsynopsisdiv>
 
@@ -95,6 +96,35 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name
         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 overriden 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>
+       </para>
+       <para>
         Remember that the extension itself is not considered to be within any
         schema: extensions have unqualified names that must be unique
         database-wide.  But objects belonging to the extension can be within
@@ -139,6 +169,18 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name
        </para>
       </listitem>
      </varlistentry>
+
+     <varlistentry>
+      <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.
+       </para>
+      </listitem>
+     </varlistentry>
   </variablelist>
  </refsect1>