如何對升級 RDS for PostgreSQL 執行個體時發生的 PostGIS 擴充功能相關問題進行疑難排解？

簡短描述

Amazon RDS PostgreSQL 執行個體的主要版本升級可能會因多種原因而失敗。最常見的原因是過時的 PostGIS 延伸模組或相依擴充功能。在執行主要版本升級之前，必須更新 PostGIS 和相依擴充功能。相依擴充功能包括 address_standardizer、address_standardizer_data_us、postgis_tiger_geocoder、postgis_topology 或 postgis_raster。

首先，確定 RDS for PostgreSQL 執行個體主要版本升級是否因為擴充功能而失敗。如果擴充功能有問題，請升級 PostGIS 及其相依擴充功能。

解決方法

檢查執行個體是否需要擴充功能升級

為確定 RDS for PostgreSQL 執行個體主要版本升級是否因擴充功能而失敗，請完成下列工作。

檢視執行個體的事件。您可能會看到類似下列的事件：

Database instance is in a state that cannot be upgraded: PreUpgrade checks failed: The instance could not be upgraded because one or more databases have settings or usages that are not compatible with the target engine version. Please check the precheck log file for more details

檢視執行個體的預先檢查日誌檔。在主要版本升級中，RDS for PostgreSQL 會對執行個體執行預先檢查程序。您可以在 pg\ _upgrade\ _precheck.log 檔案中找到預先檢查期間發生的問題。

如果預先檢查日誌檔包含類似下列範例的訊息，則升級程序因 PostGIS 或相依擴充功能而失敗：

------------------------------------------------------------------Upgrade could not be run on Sun May 22 14:20:45 2022------------------------------------------------------------------
The instance could not be upgraded from 9.6.22.R1 to 12.7.R1 because of following reasons.
Please take appropriate action on databases that have usages incompatible with requested major engine version upgrade and try again.
- Following usages in database 'test_db' need to be corrected before upgrade:
-- The instance could not be upgraded because the PostGIS extension and its dependent extensions (address_standardizer,
address_standardizer_data_us, postgis_tiger_geocoder, postgis_topology, postgis_raster) installation in one or more databases is
not compatible with your desired upgrade path. Please upgrade postgis and its dependent extensions to version supported in requested version.
----------------------- END OF LOG  ----------------------

若要檢查已安裝的 PostGIS 版本及其相依擴充功能，請執行下列命令：

postgres=> select * FROM pg_available_extensions where name like '%postgis%';
postgres=> select * FROM pg_available_extensions where name like '%address_standardizer%';
postgres=> select probin from pg_proc where proname = 'postgis_raster_lib_version';

installed_version 欄中的值顯示目前安裝的擴充功能版本。如果此欄沒有值，則表示擴充功能未安裝。

準備 PostGIS 擴充功能升級

升級 RDS for PostgreSQL 執行個體時，請執行下列動作：

• 使用多個步驟執行升級。
• 在升級 RDS for PostgreSQL 執行個體之前，請先在每個步驟中升級擴充功能版本。

執行 SELECT postgis_full_version() 命令。在輸出中，檢查是否有擴充功能在等待升級。

具有必須升級的擴充功能的範例輸出：

postgres=>  SELECT postgis_full_version();
                                                                                                                        postgis_full_version                                                                                                                          
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
POSTGIS="2.2.5 r15298" GEOS="3.6.2-CAPI-1.10.2 4d2925d6" PROJ="Rel. 4.9.3, 15 August 2016" GDAL="GDAL 2.1.4, released 2017/06/23" LIBXML="2.9.1" LIBJSON="0.12.1" (core procs from "2.2.2 r14797" need upgrade) RASTER (raster procs from "2.2.2 r14797" need upgrade)

沒有需要升級的擴充功能的範例輸出：

postgres=> SELECT postgis_full_version();
                                                                                postgis_full_version                                                                                 
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
POSTGIS="2.3.7 r16523" PGSQL="96" GEOS="3.6.2-CAPI-1.10.2 4d2925d6" PROJ="Rel. 4.9.3, 15 August 2016" GDAL="GDAL 2.1.4, released 2017/06/23" LIBXML="2.9.1" LIBJSON="0.12.1" RASTER
(1 row)

選擇可升級的版本

確認 pg_extension 目錄表格輸出中的 PostGIS 安裝和版本資訊是否與 SELECT postgis_full_version() 命令相符。

執行下列命令，檢查 RDS for PostgreSQL 執行個體中安裝的擴充功能的下一個支援版本：

postgres=> SELECT name,version,installed FROM pg_catalog.pg_available_extension_versions WHERE name LIKE 'postgis%' AND version NOT LIKE ALL (array['%next%','%unpackaged%']) order by 2,1;
postgres=> SELECT name,version,installed FROM pg_catalog.pg_available_extension_versions WHERE name LIKE 'address%' AND version NOT LIKE ALL (array['%next%','%unpackaged%']) order by 2,1;

選取可升級的最高支援版本。

**注意：**在 PostgreSQL 引擎升級之前，請檢查 pg\ _extension 表以確認沒有 "next"、"dev" 或 "unpackaged" 擴充功能版本。如果您使用這些版本中的任何一個，則最佳做法是先移至標準擴充功能版本。

升級擴充功能

若要升級擴充功能，請執行下列其中一個命令。

如果已安裝的 PostGIS 版本為 2.5 或更高版本，請執行下列命令：

SELECT postgis_extensions_upgrade();


若要將 PostGIS 從 2.5.x 版升級至 3.x 版，請執行下列命令兩次：

SELECT postgis_extensions_upgrade();

如果已安裝的 PostGIS 版本為 2.4 或更早版本，請執行 ALTER EXTENSION 命令：

ALTER EXTENSION PostgreSQL-extension UPDATE TO 'new-version';

如果您安裝了多個 PostGIS 模組，例如 postgis_topology，則單獨更新每個模組。下列範例顯示了使用 ALTER EXTENSION 命令更新多個模組的最佳做法：

ALTER EXTENSION postgis UPDATE TO 'new-version';

ALTER EXTENSION postgis_topology UPDATE TO 'new-version';

ALTER EXTENSION postgis_tiger_geocoder UPDATE TO 'new-version';


**注意：**擴充功能安裝在資料庫層級。確保在安裝它們的所有資料庫中更新擴充功能。

如果目前安裝的 PostGIS 版本為 3.0 或更高版本，則必須分別更新點陣式函數。如果您不使用點陣式函數，請在更新擴充功能之後執行下列命令：

postgres=> DROP EXTENSION postgis_raster;

更新擴充功能之後，對支援的擴充功能版本升級 RDS for PostgreSQL 引擎版本。

升級執行個體之後，重複步驟以檢查已安裝的 PostGIS 版本及其相依擴充功能。

**注意：**將 PostGIS 及其相依的擴充功能升級到目前 RDS for PostgreSQL 版本上的最新支援版本是最佳做法。