I ran your question through Gemini.
The following advice may be appropriate.
When PostgreSQL extensions (like PostGIS or TimescaleDB) report version mismatches during an upgrade, pg_upgrade will halt. To fix this, align the old cluster’s extension catalog with the physical shared libraries installed on the new cluster or use logical replication for a safer, decoupled migration. [1, 2, 3, 4]
Method 1: The In-Place pg_upgrade Fix (Downtime Required) [1]
If you are running pg_upgrade and it fails because your old database extension version is behind the new binaries, you need to update the extension’s metadata in the old cluster before upgrading. [1]
- Install Missing Libraries on Target: Ensure the new PostgreSQL environment has the exact same extension shared libraries installed as the old cluster. [1]
- Update the Extension Catalogs: Start the old server, connect to each database, and run:
sql
ALTER EXTENSION <extension_name> UPDATE;
Use code with caution.
3.Note: For complex extensions like PostGIS, ensure all related components are updated (e.g., ALTER EXTENSION postgis_topology UPDATE;)*.
4. Re-run pg_upgrade: Once the old catalog versions match or exceed the version expected by the new cluster’s binaries, the pg_upgrade checks will pass. [1]
Method 2: Logical Replication / pg_dump (Zero to Minimal Downtime)
If the shared object versions are drastically incompatible (e.g., jumping multiple major versions of an extension), an in-place binary upgrade might not work. A logical migration using pg_dumpall or pg_dump bypasses shared library discrepancies entirely. [1, 2]
- Set Up the New Cluster: Install the new PostgreSQL release and the target version of your extension.
- Initialize: Create a new, empty database on the target and run
CREATE EXTENSION <extension_name>; to let the new cluster build its own native catalogs.
- Transfer Schema & Data: Migrate your schema with
pg_dump --schema-only and your data with pg_dump --data-only, or use native PostgreSQL Logical Replication to sync data with minimal downtime. [1, 2, 3, 4, 5]
Post-Migration Steps
Whenever an extension is updated or a database is migrated across major versions, extension objects require post-upgrade compiling and statistics updates: [1]
- Update Extension Catalogs on Target: Run
ALTER EXTENSION <extension_name> UPDATE; in your new cluster.
- Update Query Statistics: Run
ANALYZE; to ensure your query planner isn’t using outdated plans.
- Validate C-Library Functions: Execute a smoke test that calls the extension’s native library functions (e.g.,
SELECT PostGIS_Full_Version(); or testing custom datatypes). [1, 2, 3, 4]
To note, if PostGIS is also installed then this will also result in a library mismatch moving 4 major releases.
Additionally, the PostgreSQL mailing list may be suitable for edge cases during this discouraged process.
Lastly, you may opt to pull a silver support request through my.apiscp.com. I would be able to take a look at migrating things fully over to 17 or at least unwinding your steps back 13 later this afternoon.
TL;DR use pg_dump (or pg_dumpall) if library extensions cannot be synchronized between these releases. The system database for the platform is named: “apnscp”.
