Add @extschema:name@ and no_relocate options to extensions.

@extschema:name@ extends the existing @extschema@ feature so that
we can also insert the schema name of some required extension,
thus making cross-extension references robust even if they are in
different schemas.

However, this has the same hazard as @extschema@: if the schema
name is embedded literally in an installed object, rather than being
looked up once during extension script execution, then it's no longer
safe to relocate the other extension to another schema.  To deal with
that without restricting things unnecessarily, add a "no_relocate"
option to extension control files.  This allows an extension to
specify that it cannot handle relocation of some of its required
extensions, even if in themselves those extensions are relocatable.
We detect "no_relocate" requests of dependent extensions during
ALTER EXTENSION SET SCHEMA.

Regina Obe, reviewed by Sandro Santilli and myself

Discussion: https://postgr.es/m/003001d8f4ae$402282c0$c0678840$@pcorp.us

1 files changed, 42 insertions, 3 deletions

diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml
index b70cbe83aec..218940ee5ce 100644
--- a/doc/src/sgml/extend.sgml
+++ b/doc/src/sgml/extend.sgml
@@ -739,6 +739,21 @@ RETURNS anycompatible AS ...
       </listitem>
      </varlistentry>
 
+     <varlistentry id="extend-extensions-files-no-relocate">
+      <term><varname>no_relocate</varname> (<type>string</type>)</term>
+      <listitem>
+       <para>
+        A list of names of extensions that this extension depends on that
+        should be barred from changing their schemas via <command>ALTER
+        EXTENSION ... SET SCHEMA</command>.
+        This is needed if this extension's script references the name
+        of a required extension's schema (using
+        the <literal>@extschema:<replaceable>name</replaceable>@</literal>
+        syntax) in a way that cannot track renames.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry id="extend-extensions-files-superuser">
       <term><varname>superuser</varname> (<type>boolean</type>)</term>
       <listitem>
@@ -902,8 +917,9 @@ RETURNS anycompatible AS ...
        For such an extension, set <literal>relocatable = false</literal> in its
        control file, and use <literal>@extschema@</literal> to refer to the target
        schema in the script file.  All occurrences of this string will be
-       replaced by the actual target schema's name before the script is
-       executed.  The user can set the target schema using the
+       replaced by the actual target schema's name (double-quoted if
+       necessary) before the script is executed.  The user can set the
+       target schema using the
        <literal>SCHEMA</literal> option of <command>CREATE EXTENSION</command>.
       </para>
      </listitem>
@@ -916,7 +932,7 @@ RETURNS anycompatible AS ...
        will prevent use of the <literal>SCHEMA</literal> option of <command>CREATE
        EXTENSION</command>, unless it specifies the same schema named in the control
        file.  This choice is typically necessary if the extension contains
-       internal assumptions about schema names that can't be replaced by
+       internal assumptions about its schema name that can't be replaced by
        uses of <literal>@extschema@</literal>.  The <literal>@extschema@</literal>
        substitution mechanism is available in this case too, although it is
        of limited use since the schema name is determined by the control file.
@@ -969,6 +985,29 @@ SET LOCAL search_path TO @extschema@, pg_temp;
      setting of <varname>search_path</varname> during creation of dependent
      extensions.
     </para>
+
+    <para>
+     If an extension references objects belonging to another extension,
+     it is recommended to schema-qualify those references.  To do that,
+     write <literal>@extschema:<replaceable>name</replaceable>@</literal>
+     in the extension's script file, where <replaceable>name</replaceable>
+     is the name of the other extension (which must be listed in this
+     extension's <literal>requires</literal> list).  This string will be
+     replaced by the name (double-quoted if necessary) of that extension's
+     target schema.
+     Although this notation avoids the need to make hard-wired assumptions
+     about schema names in the extension's script file, its use may embed
+     the other extension's schema name into the installed objects of this
+     extension.  (Typically, that happens
+     when <literal>@extschema:<replaceable>name</replaceable>@</literal> is
+     used inside a string literal, such as a function body or
+     a <varname>search_path</varname> setting.  In other cases, the object
+     reference is reduced to an OID during parsing and does not require
+     subsequent lookups.)  If the other extension's schema name is so
+     embedded, you should prevent the other extension from being relocated
+     after yours is installed, by adding the name of the other extension to
+     this one's <literal>no_relocate</literal> list.
+    </para>
    </sect2>
 
    <sect2 id="extend-extensions-config-tables">