Re: pg_upgrade does not upgrade pg_stat_statements properly

On 2021-Jul-29, Bruce Momjian wrote:

> +     If the old cluster used extensions, whether from
> +     <filename>contrib</filename> or some other source, it used
> +     shared object files (or DLLs) to implement these extensions, e.g.,
> +     <filename>pgcrypto.so</filename>.  Now, shared object files matching
> +     the new server binary must be installed in the new cluster, usually
> +     via operating system commands.  Do not load the schema definitions,
> +     e.g., <command>CREATE EXTENSION pgcrypto</command>, because these
> +     will be copied from the old cluster.  (Extensions should be upgraded
> +     later using <literal>ALTER EXTENSION ... UPGRADE</literal>.)

I propose this:

<para>
  If the old cluster used shared-object files (or DLLs) for extensions
  or other loadable modules, install recompiled versions of those files
  onto the new cluster.
  Do not install the extension themselves (i.e., do not run
  <command>CREATE EXTENSION</command>), because extension definitions
  will be carried forward from the old cluster.
</para>

<para>
  Extensions can be upgraded after pg_upgrade completes using
  <command>ALTER EXTENSION ... UPGRADE</command>, on a per-database
  basis.
</para>

I suggest " ... for extensions or other loadable modules" because
loadable modules aren't necessarily for extensions.  Also, it's
perfectly possible to have extension that don't have a loadable module.

I suggest "extension definitions ... carried forward" instead of
"extensions ... copied" (your proposed text) to avoid the idea that
files are copied; use it instead of "schema definitions ... upgraded"
(the current docs) to avoid the idea that they are actually upgraded;
also, "schema definition" seems a misleading term to use here.

I suggest "can be upgraded" rather than "should be upgraded" because
we're not making a recommendation, merely stating the fact that it is
possible to do so.