Rearrange extension-related views as per recent discussion.

The original design of pg_available_extensions did not consider the
possibility of version-specific control files.  Split it into two views:
pg_available_extensions shows information that is generic about an
extension, while pg_available_extension_versions shows all available
versions together with information that could be version-dependent.
Also, add an SRF pg_extension_update_paths() to assist in checking that
a collection of update scripts provide sane update path sequences.

2 files changed, 96 insertions, 8 deletions

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index e93347992f2..4f7dc6843dc 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -6331,6 +6331,11 @@
      </row>
 
      <row>
+      <entry><link linkend="view-pg-available-extension-versions"><structname>pg_available_extension_versions</structname></link></entry>
+      <entry>available versions of extensions</entry>
+     </row>
+
+     <row>
       <entry><link linkend="view-pg-cursors"><structname>pg_cursors</structname></link></entry>
       <entry>open cursors</entry>
      </row>
@@ -6460,23 +6465,78 @@
      </row>
 
      <row>
-      <entry><structfield>version</structfield></entry>
+      <entry><structfield>default_version</structfield></entry>
       <entry><type>text</type></entry>
-      <entry>Version string from the extension's control file</entry>
+      <entry>Name of default version, or <literal>NULL</literal> if none is
+       specified</entry>
      </row>
 
      <row>
-      <entry><structfield>installed</structfield></entry>
+      <entry><structfield>installed_version</structfield></entry>
       <entry><type>text</type></entry>
       <entry>Currently installed version of the extension,
        or <literal>NULL</literal> if not installed</entry>
      </row>
 
      <row>
-      <entry><structfield>schema</structfield></entry>
+      <entry><structfield>comment</structfield></entry>
+      <entry><type>text</type></entry>
+      <entry>Comment string from the extension's control file</entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </table>
+
+  <para>
+   The <structname>pg_available_extensions</structname> view is read only.
+  </para>
+ </sect1>
+
+ <sect1 id="view-pg-available-extension-versions">
+  <title><structname>pg_available_extension_versions</structname></title>
+
+  <indexterm zone="view-pg-available-extension-versions">
+   <primary>pg_available_extension_versions</primary>
+  </indexterm>
+
+  <para>
+   The <structname>pg_available_extension_versions</structname> view lists the
+   specific extension versions that are available for installation.  This view
+   can only be read by superusers.  See also the <link
+   linkend="catalog-pg-extension"><structname>pg_extension</structname></link>
+   catalog, which shows the extensions currently installed.
+  </para>
+
+  <table>
+   <title><structname>pg_available_extension_versions</> Columns</title>
+
+   <tgroup cols="3">
+    <thead>
+     <row>
+      <entry>Name</entry>
+      <entry>Type</entry>
+      <entry>Description</entry>
+     </row>
+    </thead>
+
+    <tbody>
+     <row>
+      <entry><structfield>name</structfield></entry>
       <entry><type>name</type></entry>
-      <entry>Name of the schema where the extension is installed,
-       or <literal>NULL</literal> if not installed</entry>
+      <entry>Extension name</entry>
+     </row>
+
+     <row>
+      <entry><structfield>version</structfield></entry>
+      <entry><type>text</type></entry>
+      <entry>Version name</entry>
+     </row>
+
+     <row>
+      <entry><structfield>installed</structfield></entry>
+      <entry><type>bool</type></entry>
+      <entry>True if this version of this extension is currently
+       installed</entry>
      </row>
 
      <row>
@@ -6486,6 +6546,20 @@
      </row>
 
      <row>
+      <entry><structfield>schema</structfield></entry>
+      <entry><type>name</type></entry>
+      <entry>Name of the schema that the extension must be installed into,
+       or <literal>NULL</literal> if partially or fully relocatable</entry>
+     </row>
+
+     <row>
+      <entry><structfield>requires</structfield></entry>
+      <entry><type>name[]</type></entry>
+      <entry>Names of prerequisite extensions,
+       or <literal>NULL</literal> if none</entry>
+     </row>
+
+     <row>
       <entry><structfield>comment</structfield></entry>
       <entry><type>text</type></entry>
       <entry>Comment string from the extension's control file</entry>
@@ -6495,9 +6569,9 @@
   </table>
 
   <para>
-   The <structname>pg_available_extensions</structname> view is read only.
+   The <structname>pg_available_extension_versions</structname> view is read
+   only.
   </para>
-
  </sect1>
 
  <sect1 id="view-pg-cursors">
diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml
index 6dc42e4ea1b..63a917d3c94 100644
--- a/doc/src/sgml/extend.sgml
+++ b/doc/src/sgml/extend.sgml
@@ -765,6 +765,20 @@ SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entr
      path than to move ahead one version at a time.  If the downgrade script
      drops any irreplaceable objects, this will yield undesirable results.
     </para>
+
+    <para>
+     To check for unexpected update paths, use this command:
+<programlisting>
+SELECT * FROM pg_extension_update_paths('<replaceable>extension_name</>');
+</programlisting>
+     This shows each pair of distinct known version names for the specified
+     extension, together with the update path sequence that would be taken to
+     get from the source version to the target version, or <literal>NULL</> if
+     there is no available update path.  The path is shown in textual form
+     with <literal>--</> separators.  You can use
+     <literal>regexp_split_to_array(path,'--')</> if you prefer an array
+     format.
+    </para>
    </sect2>
 
    <sect2>