PostGIS After pg_upgrade: Fixing Version Mismatches and Broken Functions

PostgreSQL major version upgrades via pg_upgrade are well-documented, well-tested, and generally smooth. But if you run PostGIS, there is a post-upgrade step that the documentation buries in a single sentence -- and skipping it breaks every spatial function in your database. What pg_upgrade Does (and Doesn't Do) pg_upgrade migrates the data directory: system catalogs, user tables, indexes, and extension metadata. It copies the catalog entry that says "PostGIS 3.4.0 is installed in this database" to the new cluster. What it does not do is install PostGIS 3.4.0 in the new cluster's library directory. The old .so files were compiled against PG 15's internal ABI. When PG 16 tries to load them, one of two things happens: The file doesn't exist. The new PG 16 installation has a clean lib/ directory. The catalog references $libdir/postgis-3 , but that file is only in PG 15's lib path. Error: could not access file "$libdir/postgis-3": No such file or directory . The file exists but is incompat