[Feature]: Support in-place major upgrades with Image Volume extensions #10049

Is there an existing issue already for this feature request/idea?

• I have searched for an existing issue, and could not find anything. I believe this is a new feature request to be evaluated.

What problem is this feature going to solve? Why should it be added?

Add support for offline in-place major upgrades for Clusters using Image Volume Extensions.

This patch is a follow up of #7991 & #8495.
Given that Image Volume extensions are only usable on PostgreSQL 18 or greater, this patch won't be required until PostgreSQL 19 (or 19RC) is out.

This patch would be required to allow Clusters that utilize Image Volume Extensions to upgrade to a newer PG major version by using
offline in-place major upgrades (e.g via pg_upgrade).

Describe the solution you'd like

What's needed

From CloudNativePG

1. Modify createMajorUpgradeJobDefinition() to properly define the upgrade job that runs pg_upgrade. In detail:

   • The upgrade prepare initContainer should mount ImageVolume extensions of the old major version
   • The upgrade execute container should mount ImageVolume extensions of both old and new major versions

2. Modify the majorUpgradeCommand to support adding extra pg_upgrade options. pg_upgrade support passing configuration to either the new or old postgres command via --old-options and --new-options. This will be required to allow the instances that are being spun up by pg_upgrade to properly find extensions and libraries, configuring these options in the following way:

--old-options="-c extension_control_path='$system:/extensions/old-extension/share' -c dynamic_library_path='$libdir:/extensions/old-extension/lib'"
--new-options="-c extension_control_path='$system:/extensions/new-extension/share' -c dynamic_library_path='$libdir:/extensions/new-extension/lib'"

From core PostgreSQL

Links:

• pgsql-hackers mail thread: pg_upgrade fails when extension_control_path is used
  
• CommitFest patch: https://commitfest.postgresql.org/patch/6562/

It appears that pg_upgrade is unable perform a major upgrade when the PostgreSQL instance has extensions that are being installed from a non-default path (via dynamic_library_path / extension_control_path).

The check_loadable_libraries() function tries to load each library by running LOAD <lib> (where <lib> equals to the value of the extension's module_pathname inside its control file), which in almost all cases is defined as '$libdir/<extname>' (for example '$libdir/vector').

As such, if the library in question is not present in the default $libdir, the upgrade will fail with:

Checking for presence of required libraries                   fatal

Your installation references loadable libraries that are missing from the
new installation.  You can add these libraries to the new installation,
or remove the functions using them from the old installation.  A list of
problem libraries is in the file:
    /var/lib/postgresql/data/pgdata-new/pg_upgrade_output.d/20260217T151616.481/loadable_libraries.txt
Failure, exiting
postgres@cluster-example-1-major-upgrade:~/data/pgdata-new$ cat /var/lib/postgresql/data/pgdata-new/pg_upgrade_output.d/20260217T151616.481/loadable_libraries.txt
could not load library "$libdir/vector": ERROR:  could not access file "$libdir/vector": No such file or directory
In database: app

The expected behavior is that, after configuring the pg_upgrade command with the proper GUCs to allow locating extensions from "extra" PATHs, pg_upgrade would be able to LOAD all extensions and properly perform the major upgrade.

Describe alternatives you've considered

Do not allow upgrading Clusters that use Image Volume Extensions via offline in-place major upgrades.
Users will have to rely on one of the other Major version upgrade methods, such as dump/restore or using logical replication.

Additional context

No response

Backport?

No

Are you willing to actively contribute to this feature?

Yes

Code of Conduct

• I agree to follow this project's Code of Conduct