升級至新主要版本

選擇升級路徑:

對於最後兩條路徑,新部署不會接收在升級或備份完成後傳送到來源的變更。 請先對新版本進行測試與驗證。 在進行最終切換之前,請停止對來源的寫入操作。 接著,將複本推廣或建立備份,並將應用程式的連線設定切換至新的部署環境。

請在 目錄中 尋找適用於新部署的版本,可透過 ibmcloud cdb deployables-show,或透過 /deployables API 進行查詢。

在 API 範例中,請將 {region} 替換為部署的區域、將 {id} 替換為部署的 URL 編碼的雲端資源名稱 (CRN),並將 <IAM_TOKEN> 替換為您的 Identity and Access Management (IAM) 存取憑證。

升級要求

應用程式相容性

在正式上線前,請先在具有代表性的預備環境中測試您所選擇的升級路徑。 針對 IPMVU 排練,請將系統還原至最近的備份,以恢復至原始的 PostgreSQL 版本。 一個部署包含兩個或三個資料成員:主成員以及一個或兩個高可用性(HA)成員。 請將還原後的部署擴展至與生產環境相同的成員數量,因為高可用性成員數量越多,轉換階段 所需的時間就越長。 請確認已還原的部署環境具有完整的備份,然後將其升級至您預期的目標版本。 檢查應用程式查詢、背景工作、驅動程式、擴充功能及連線池。 記錄效能表現,以及您的應用程式出現唯讀錯誤和連線失敗的時間長度,以便日後進行比較。

請檢視自您的來源版本之後,直至(含)您的目標版本為止,每個主要版本的 發行說明。 另請參閱 角色權限變更。

此升級不會保留提交時間戳記。 升級後,對於每個在升級前已提交的交易,pg_xact_commit_timestamp() 都會傳回 NULL。 如果您的應用程式會讀取提交時間戳記,請在升級前將所需的值複製到資料表的欄位中。

擴充功能及其他物件

在進行升級之前,請先完成以下各節中適用的準備工作。 對於 IPMVU,請準備要進行升級的部署。 對於唯讀副本和還原路徑,請在建立副本或執行備份之前,先準備好來源部署。 您無法變更唯讀副本,而還原操作會在同一道程序中升級資料。 請針對您移除的物件,預先規劃任何應用程式對其的依賴關係。

延伸規格

pg_repack

pg_repack 不會阻礙升級。 您無需在升級前後刪除或重新建立它。

old_snapshot

該 old_snapshot 此模組在 PostgreSQL 17及後續版本中已不可用。 當您從 PostgreSQL 16 或更早版本升級至 PostgreSQL 17 或更新版本時,IPMVU 會在讀取唯讀模式開始之前,從每個資料庫中移除 old_snapshot。 若任何物件依賴於 old_snapshot,則升級將失敗。 若後續升級失敗,此移除操作將不會被撤銷。

若任何資料庫中已安裝 old_snapshot,請在升級前聯絡技術支援,以確認相關的依賴物件。 至於其他升級路徑,請聯絡技術支援以安排移除事宜。

anon

若已安裝 anon 第 2 版,請在每個已安裝該版本的資料庫中完成以下步驟。 請以這些表的擁有者身分執行這些指令,例如:admin。 對於 IPMVU,anon 第 2 版會在轉換階段導致升級失敗,此時資料庫無法使用,且每次重試都會以相同方式失敗。anon 第 3 版則無需執行這些步驟。 自檢查詢 10 會顯示安裝的版本,位於 extversion。

在移除遮罩規則之前,請先封鎖受遮罩角色的資料庫存取權限,這些角色僅應能查看經遮罩處理的資料。 請持續封鎖其存取權限,直到您在升級完成後還原並驗證遮罩規則和角色標籤為止。

  1. 請記錄遮罩規則與被遮罩的角色,以便在升級後能將其還原。

    SELECT objtype, objname, label
    FROM pg_catalog.pg_seclabels
    WHERE provider = 'anon';
    
  2. 移除所有遮罩規則。

    SELECT anon.remove_masks_for_all_columns();
    
  3. 從步驟 1 中列出的每個角色中,移除被遮蓋的標籤。 在 PostgreSQL 16 及後續版本中,此操作需要為該角色啟用「ADMIN」選項。 如需更多資訊,請參閱《 版本升級期間的角色權限問題 》。

    SECURITY LABEL FOR anon ON ROLE <role_name> IS NULL;
    
  4. 使用 cascade 選項刪除 anon 延伸。 「級聯」選項也會移除依賴於 anon`` 的物件,例如遮罩檢視與函式。 請記錄這些定義,以便在升級後能夠重新建立它們。

    DROP EXTENSION anon CASCADE;
    
  5. 升級完成後,請重新啟用「anon」,重新套用已記錄的遮罩規則與角色標籤,並在恢復受遮罩角色的存取權限之前,先驗證遮罩是否正確。

PostGIS

若您使用 PostGIS,,請在升級之前,先將每個使用該函式的資料庫進行升級 PostgreSQL:

SELECT postgis_extensions_upgrade();

驗證擴充功能版本:

SELECT postgis_full_version();
earthdistance

若某個索引或儲存的生成欄位使用了 earthdistance 版本 1.1 中的函數(例如 ll_to_earth() ),則IPMVU會在轉換階段發生失敗。 當物件透過您自訂的 SQL 函式使用它時,此情況同樣適用。 PostgreSQL 第 14 和 15 項僅提供版本 1.1。 請在每個資料庫中執行 自助查詢 13,然後處理清單中列出的每個物件:

  • 若您使用的是 PostgreSQL 16 或 17,請在升級前先更新該擴充功能:

    ALTER EXTENSION earthdistance UPDATE;
    
  • 在 PostgreSQL 14 或 15 中,若 used_function 是您自訂的函式之一,請在其中新增 search_path 設定:

    ALTER FUNCTION <used_function> SET search_path = ibm_extension, pg_catalog;
    
  • 在 PostgreSQL 14 或 15 版本中,若 used_function 屬於 earthdistance 函式,請在升級前刪除清單中的索引。 若要保留已列出的生成欄位中的值,請使用 ALTER TABLE <table_name> ALTER COLUMN <column_name> DROP EXPRESSION; 將其轉換為一般欄位。 升級完成後,請執行 ` `ALTER EXTENSION earthdistance UPDATE;,然後重新建立您先前移除的內容。 如果您的目標是 PostgreSQL 15,則此更新將無效,且您重新建立的物件會以相同方式阻礙您後續的升級。 為避免此情況,請升級至 PostgreSQL 16 或更新版本。

pgRouting

若您的部署環境執行的是「PostgreSQL」16 或 17 版,且您要升級至「PostgreSQL」18 版,請檢查每個已安裝「pgRouting」的資料庫。 PostgreSQL 這 18 個部署不包含 pgRouting 3.5 這個函式庫。 當任何函式使用該函式庫時,在進入唯讀模式之前,對 PostgreSQL 18 的 IPMVU 會因相容性檢查失敗而失敗。 請勿期待會出現爭執:

SELECT DISTINCT p.probin
FROM pg_catalog.pg_proc AS p
WHERE p.probin = '$libdir/libpgrouting-3.5';

若查詢結果返回一行資料,請在升級前將 更新 pgRouting 為您當前部署所提供的最新版本,然後再次執行該查詢:

ALTER EXTENSION pgrouting UPDATE;

pgRouting 4.0 版本移除了若干功能,例如 pgr_createTopology、及 pgr_analyzeGraph``pgr_nodeNetwork,並對其他功能進行了變更。 請先在 pgRouting 預備環境中使用 4.0 測試您的應用程式。 若使用者需要已移除的功能,請在升級至 PostgreSQL 18 之前聯絡技術支援。 從 PostgreSQL 16 開始,您也可以升級至 PostgreSQL 17,該版本包含 3.5 函式庫。

索引、分區鍵及生成欄位中的 SQL 函數

在轉換階段,IPMVU 會針對每個索引、分區鍵及儲存生成欄位,重新建立其定義,並將搜尋路徑設為空。 若其中一個物件使用 LANGUAGE sql 函式,且該函式的字串本體直接或透過網域檢查約束,指稱位於 pg_catalog 之外且未指定其模式的物件,則此步驟將失敗。 擴展統計資料對具有外鍵的資料表具有相同的效果。 在索引中,若呼叫時指定了安裝擴充套件的 ibm_extension 模式,該呼叫也會失敗。 此錯誤發生於資料庫無法存取時,且每次重試均以相同方式失敗。

在每個資料庫中執行 自檢查詢 12。 針對每個列出的函式,請新增一個 search_path 設定,其中列出該函式本體所使用的所有模式名稱。 或者,將其字串本體替換為符合 SQL 標準的本體。 請以該函式的擁有者身分執行這些陳述式。 例如:

ALTER FUNCTION f_unaccent(text) SET search_path = ibm_extension, pg_catalog;
CREATE OR REPLACE FUNCTION f_unaccent(text) RETURNS text
  LANGUAGE sql IMMUTABLE PARALLEL SAFE STRICT
  RETURN ibm_extension.unaccent('ibm_extension.unaccent', $1);

請保持每個函數的結果及其他屬性不變,因為索引和生成欄位會儲存其結果,而分區表會根據這些結果來路由資料列。 當設定為「search_path」時,PostgreSQL 將不再將該函式展開至呼叫它的查詢中,因此這些查詢的執行速度可能會變慢。 SQL 標準機構並不會保護其所呼叫的字串型函式,因此也請修正這些函式。 請重複執行此查詢,直到其未返回任何資料列為止。 如果清單中列出了您未擁有的功能,請在升級前聯絡技術支援。

若您是從 PostgreSQL 16 或更早版本升級至 PostgreSQL 17 或更新版本,請一併執行 自檢查詢 17。 PostgreSQL 17 及後續版本會以受限的搜尋路徑執行維護指令。 任何語言中,若某個函式被索引、實體化檢視或擴展統計資料所使用,則該函式需要擁有專屬的 search_path 設定。 否則,升級後,針對受影響的物件,ANALYZE、REINDEX、CLUSTER、VACUUM FULL 以及 REFRESH MATERIALIZED VIEW 將無法正常運作。 請為每個如前例所示、在命名物件時未包含其模式的名稱之列出函式,設定其搜尋路徑。 如需更多資訊,請參閱 PostgreSQL 17 的遷移說明。

使用已移除系統名稱的物件

每個主要版本都會移除或重新命名部分系統目錄欄位、函式及設定參數。 例如,PostgreSQL 17 移除了 pg_stat_bgwriter 中的檢查點欄位,而 PostgreSQL 16 將 force_parallel_mode 參數重新命名為 debug_parallel_query。 預檢功能無法偵測到使用以下名稱的物件:

  • 若某個檢視、實體化檢視或聚合使用了已被移除的名稱,則 IPMVU 會在轉換階段失敗。 具有 SQL 標準本體的函式,以及其已移除參數的函式、角色或資料庫設定,其效果相同。
  • 其他函式與程序、pg_cron 工作,以及使用已移除名稱的應用程式查詢,在首次於新版本上執行時將會失敗。 這可能發生在寫入作業恢復之前。

在每個資料庫中執行 自檢查詢 14。 將清單中所有 removed_in 版本等於或低於您目標版本的物件進行變更或刪除。 使用自檢查詢 7 檢查角色和資料庫設定。 請在目標版本的預生產環境中測試您的應用程式及監控查詢。

邏輯複製槽

只要存在任何邏輯複製槽(包括非活躍槽以及由 wal2json 使用的槽),IPMVU 便會無法通過預檢查。 已刪除的槽位無法恢復,且新槽位不會包含舊槽位所保留的變更。 升級前:

  1. 請記錄每個插槽的名稱、外掛程式,以及透過 自檢查詢 2 所對應的資料庫。

  2. 請暫停來源資料的寫入,直到您在升級後恢復消費者,或計劃重新同步下游資料為止。

  3. 讓消費者處理待處理的變更,然後中止這些變更。 請讓它們保持停止狀態,並關閉自動重新連線功能,直到該任務顯示為「已完成」為止。

  4. 請使用 ibmcloud cdb postgresql replication-slot-delete,或使用「刪除邏輯複製槽」API。 admin 使用者無法透過 SQL 刪除複製槽。

    ibmcloud cdb postgresql replication-slot-delete <NAME|CRN> <SLOT_NAME>
    
  5. 升級完成後,請依照《 wal2json 設定指南 》中的說明重新建立插槽。

wal2json 這是一個邏輯解碼輸出外掛程式,而非透過「CREATE EXTENSION」所建立的擴充套件。

邏輯訂閱

邏輯訂閱會接收來自發佈者的變更。 其複製槽位於發佈端,因此槽查詢中並未列出該槽。

若您的部署環境執行的是「PostgreSQL」16 或更早版本,只要存在任何邏輯訂閱(包括已停用的訂閱),IPMVU 便會無法通過預檢查。 從這些版本進行升級時,訂閱的同步狀態將不會被保留。 在進行升級之前,請與發行商負責人商定如何移除並重新建立各項訂閱,以及如何重新同步資料。 接著,使用 訂閱者功能 刪除這些訂閱。 delete_subscription 函式也會在發佈者端移除訂閱的槽位;若發佈者無法連線,或該槽位已不存在,則此函式會失敗。 在這種情況下,請先執行 disable_subscription ,接著執行 subscription_slot_none ,然後再執行 delete_subscription``。 接著,請發佈者的擁有者刪除該槽位,因為它會持續在發佈者端保留交易日誌。

若您的部署環境執行的是 PostgreSQL 17 或更新版本,訂閱可保留,但必須符合目標版本的 邏輯複製升級要求。 此升級版本最多支援 10 個訂閱。 若數量更多,則會在進入唯讀模式之前就無法通過相容性檢查。 在升級前,請使用 disable_subscription 停用訂閱;升級完成後,請使用 enable_subscription 重新啟用訂閱。

UNLOGGED 資料表與序列

PostgreSQL 不會將對 UNLOGGED 中的資料表和序列所做的變更寫入交易日誌。 它不會將這些設定複製給其他成員,且會在發生故障轉移或還原後將其重設。 所有升級路徑均不會保留其內容:

  • 當 IPMVU 在新版本上重新啟動 PostgreSQL 時,會將這些設定重置;而在完成階段切換主要角色時,也會再次重置。 升級失敗也會將它們重置。
  • 已晉升的唯讀複本與已還原的備份,其 UNLOGGED 資料表初始為空,且 UNLOGGED 序列已重置。

升級後,UNLOGGED 中的資料表將清空,而 UNLOGGED 中的序列將重置。 在該任務顯示為「已完成」之前,您對這些物件所做的任何變更都可能遺失。 在進行升級之前,請使用 自檢查詢 11 來識別每個資料庫中的這些物件,並規劃如何處理每個物件。

  • 若要保留資料表的內容,請使用 ALTER TABLE <table_name> SET LOGGED;`` 進行轉換。 SET LOGGED 也會轉換該資料表的索引及其擁有的序列。 在轉換任何透過外鍵引用該資料表的資料表之前,請先轉換該被引用資料表。 或者,您可以先匯出內容,待任務顯示為「已完成」後再重新載入。
  • 若某個序列會為已記錄的資料表產生值,請使用 ALTER SEQUENCE <sequence_name> SET LOGGED;`` 進行轉換。 否則,請暫停所有使用該資源的應用程式,直到該任務顯示為「已完成」為止。 接著,請使用 setval 函式將其設定為高於目前使用中的最高值。

SET LOGGED 重新寫入資料表,並在操作完成前暫停所有讀寫作業。 它所產生的交易日誌資料量,也大約與該資料表及其索引所佔用的空間相當。 在提交升級之前,請務必預先將大型資料表轉換完畢,並使用自檢查詢 5 來確認交易日誌已歸檔。 升級後,您可以使用 ALTER TABLE <table_name> SET UNLOGGED;`` 將資料表還原。

對於 IPMVU 而言,即使是一個空的「UNLOGGED」表,也會導致服務重新建構每個高可用性成員,從而延長寫入操作被阻塞的時間。 如需更多資訊,請參閱「升級期間的可用性」。 若要避免此重建,請將所有 UNLOGGED 資料表轉換為其他類型,或刪除不再需要的資料表。執行 TRUNCATE 並不會避免重建。 UNLOGGED 序列不會觸發重建。 在 PostgreSQL 16 和 17 中,SET LOGGED 本身就是一項批量操作,仍可能導致資料庫重建,因此請預先做好相關規劃。

就地進行主要版本升級

完成 所有準備工作 後,請使用以下所述的 UI、API、CLI 或 Terraform 程序。

在 IPMVU 中,此服務會就地升級主節點,並根據各高可用性成員現有的資料檔進行升級。 當所有 HA 成員都能重複使用其資料檔時,寫入操作僅會短暫受阻。 所需時間主要取決於資料庫物件的數量以及資料庫活動的程度,而非儲存的資料量。

在某些情況下,該服務會改為將整個資料庫複製到高可用性成員節點上,這會導致寫入操作被阻塞更長的時間。 其他情況會導致在寫入被阻斷後,升級失敗。 預檢無法偵測到這些狀況,因此請在提交升級前先解決這些問題。 有關此清單,請參閱 「預檢查無法偵測到的狀況」。

提交 IPMVU 後,您將無法取消該請求,也無法對現有的部署進行降級。 此服務在升級前不會執行資料備份,因此請先建立並驗證一個 隨選備份。

升級期間的可用性

IPMVU 的運作分為以下幾個階段。 當唯讀階段開始時,寫入操作會暫停;當服務解除唯讀模式時,寫入操作便會恢復。 在轉換階段期間,亦無法進行讀取操作。

IPMVU 的各階段與可用性
階段 會發生什麼事 讀取 寫入
檢查 該服務會等待待處理的部署變更完成,並執行 預檢查。 它會檢查主節點與高可用性(HA)成員的升級相容性,並暫停自動故障轉移。 可用 可用
唯讀 此服務會將所有資料庫中的新交易設為唯讀,並終止所有客戶端會話。 接著,它會等待高可用性 (HA) 成員及交易日誌歸檔作業跟上進度。 可用 已封鎖
轉換 此服務會停止所有成員節點上的 PostgreSQL 服務,並將主節點升級。 在可行情況下,它會根據該高可用性成員現有的資料檔來升級該成員。 無法使用 無法使用
重新啟動 升級後的主節點以唯讀模式啟動,且高可用性 (HA) 成員也隨之啟動。 若任何成員無法重複使用已升級主節點的資料檔案,此服務將重新建立該成員。 可用 已封鎖
撰寫履歷 此服務會解除唯讀模式,並再次終止所有客戶端連線。 可用 可用
完成 該服務會等待每個高可用性 (HA) 成員完成同步。 接著,該服務會逐一重新啟動各成員節點,以完成將部署遷移至新版本的作業。 在重新啟動主節點之前,該服務會將主節點角色切換至另一位成員,此舉將終止客戶端連線。 接著,該服務會移除升級檔案、將升級後的備份排入佇列,並將這些任務標記為「已完成」。 可使用,但轉換期間除外 可使用,但轉換期間除外

在至少一名 HA 成員已追上進度,且每兩名 HA 成員中有一名已追上進度或正在重建之後,才會撰寫簡歷。 該服務會將整個資料庫複製到無法重複使用其資料檔的高可用性 (HA) 成員上,藉此重建該成員。 如果每個 HA 成員都必須重新建置,則寫入操作將被阻塞,直到第一個重新建置完成為止。 對於大型資料庫而言,這可能需要數小時。 包含兩個資料節點的部署(即預設配置)僅有一個高可用性節點。 因此,任何重建操作都會阻塞寫入操作。 在以下情況下,HA 會員不得重複使用其資料檔案:

  • 任何資料庫都包含一個名為 UNLOGGED 的資料表,即使是空的資料表也不例外。 接著,該服務會重新建立每個高可用性 (HA) 成員。 請參閱 自助查詢 11,並查閱 UNLOGGED 中的資料表與序列。
  • 該部署環境執行的是 PostgreSQL 16 或 17,且資料表因批量操作或大量並行插入/更新而擴增。 批次操作包括 COPY、pg_restore、CREATE TABLE AS、CREATE MATERIALIZED VIEW、REFRESH MATERIALIZED VIEW 以及 ALTER TABLE 等指令,這些指令會重新建立資料表,例如 SET LOGGED。 由於無法事先檢查這一點,因此請預先規劃重新建置。

該服務也可能因其他無法預先確認的原因,而重新建立高可用性 (HA) 成員。 若您從備份還原一個預備部署環境進行排練,該環境可能不會顯示此類重建過程。

正在重建的高可用性 (HA) 成員會保留其先前資料檔案,直到該任務完成為止。 因此,它需要至少與其資料所佔空間相等的可用磁碟空間。 在提交升級之前,請確保每個資料成員所佔用的空間遠低於其可用磁碟空間的一半。 請使用「已使用磁碟空間」指標來檢查此數值。 雖然磁碟空間預檢允許磁碟使用率最高達 90%,但重建高可用性 (HA) 成員所需的可用空間卻遠遠超過此數值。 否則,重建過程可能會因磁碟空間不足而一再失敗。 寫入操作可能會持續被阻塞數小時,直到任務失敗為止。 自動和手動磁碟擴容功能會等到升級完成後才會執行,因此請在提交升級請求之前先進行磁碟擴容。 漫長的重建過程也可能導致在恢復寫入後任務失敗。 在這兩種情況下,部署都會執行目標版本,直到支援團隊完成升級為止。 請在維護時段內預留時間進行系統重建。

在任務完成前即寫入履歷。 若要檢查寫入作業是否已恢復,請在新的工作階段中執行 SHOW default_transaction_read_only; 。 在寫入恢復後,它會傳回 off。 當進入唯讀模式時、當 PostgreSQL 因轉換而暫停時、當寫入操作恢復時、在完成階段的切換過程中,以及當服務在發生故障後恢復寫入存取權限時,客戶端會話即告結束。

在任務顯示為「已完成」之前,請避免進行持續的大量寫入操作,例如大量資料載入或批次工作。 完成階段會等待直到每個高可用性 (HA) 成員都已重播所有變更為止。 在持續的重寫入負載下,此等待可能會超時,而當寫入作業恢復後,該任務便會失敗。 在 HA 成員仍在重建期間,風險會較高。 隨後,部署程序將執行目標版本,且不會進行升級後的備份,因此技術支援部門必須完成此次升級。

若要檢查您的寫入負載是否足以讓高可用性 (HA) 成員跟上進度,請在預定的升級時間執行以下查詢。 每秒重複執行一次,持續幾分鐘,例如使用 psql 指令:\watch 1。 這項服務需要每位 HA 成員同時在 replay_lag_bytes 展示「0」。 如果這種情況從未發生,請在提交升級之前降低寫入負載。

SELECT application_name, state,
       pg_catalog.pg_wal_lsn_diff(pg_catalog.pg_current_wal_lsn(), replay_lsn) AS replay_lag_bytes
FROM pg_catalog.pg_stat_replication
ORDER BY application_name;

此升級並不會重新整理優化器的統計資料,因此在您執行 ANALYZE`` 之前,查詢可能會選擇效能較差的執行計畫。 升級至 PostgreSQL s 15、16 或 17 時,不會轉移統計資料。 升級至 PostgreSQL 18 時,大部分統計資料都會被轉移,但不包括您使用 CREATE STATISTICS 建立的擴充統計資料,或是由 PostGIS 等擴充套件所收集的統計資料。 autovacuum 程序僅會在發生足夠多的寫入操作後才會分析資料表,且絕不會分析分區資料表。 請勿等待任務完成。 一旦 SHOW default_transaction_read_only; 傳回 off,請依照「升級後」章節中的說明重新計算統計資料。

唯讀模式會為新交易設定預設值。 它不會鎖定資料庫。 即使將 default_transaction_read_only 設定為 off``,或明確地啟動讀寫交易,該會話仍可進行寫入操作。 那麼,一個其 default_transaction_read_only 設定為 off 的角色是否也能如此呢? 諸如 VACUUM、ANALYZE、REINDEX 及 CLUSTER 等維護指令仍可執行。 唯讀模式不會停止已執行的「pg_cron」工作,也不會停止 PostgreSQL 17 上已啟用的訂閱。 這類寫入操作可能會導致升級失敗。 在提交升級之前,請停止所有會覆寫唯讀模式的程序。 暫停會寫入資料或執行維護指令的排程工作(例如 pg_cron 工作),並等待正在執行的作業完成。 請依照「升級完成後」一節中的說明重新啟動它們。

在唯讀模式下,讀取操作也可能寫入交易日誌,例如在批量載入或大規模更新後,查詢首次讀取資料列時。 此操作會延遲「唯讀」與「重新啟動」階段所等待的追趕進程,導致寫入操作被阻塞的時間更長,進而可能導致升級失敗。 在提交升級之前,請對您最近載入或進行過重大修改的資料表執行 VACUUM 指令。

當服務結束一個工作階段時,直接連線至部署環境的客戶端會收到 SQLSTATE 57P01 (admin_shutdown)。在唯讀交易中進行寫入操作會因 SQLSTATE 25006 (read_only_sql_transaction) 而失敗。在轉換階段,即使您的憑證未變更,新連線仍可能因驗證錯誤而失敗,例如 SQLSTATE 28P01。 轉換完成後,請重新嘗試連線。 如果任務顯示為「失敗」後,這些錯誤仍持續發生,請聯絡技術支援。 透過連線池管理器,應用程式可以偵測到其他連線錯誤。

當設定為唯讀模式時,僅接受讀寫連線的客戶端將無法建立連線,因此直到恢復寫入功能之前,這些客戶端也無法執行讀取操作。 此規則適用於設定了 target_session_attrs=read-write 的 `libpq` 客戶,以及設定了 ` `targetServerType=primary` ` 或 ` `master 的 JDBC 客戶。 為了確保讀取操作仍可正常進行,請使用 target_session_attrs=any``,或在 libpq 14 或更高版本中使用 primary 。 若要存取 JDBC,請使用 targetServerType=any。

應用程式必須處理連線失敗和唯讀錯誤,並僅在安全的情況下重新連線,以及重試中斷的交易。 連接池化並不會消除這些要求。 應用程式可存取,並不代表升級任務已完成。

備份與復原

該服務在升級前不會進行資料備份。 在執行 IPMVU 之前,請建立並驗證一份最近的 隨選備份。 若要在升級後還原至原始版本,請將升級前的備份或還原點還原至一個執行原始版本的新部署環境中。 請明確指定版本,因為若未指定版本而執行「特定時間點還原」,所建立的部署將執行當前版本。 此選項要求原始版本仍可供新部署使用。 請說明自該時點以來所做的變更。

升級成功後,系統會將已升級的部署版本備份並排入佇列。 備份會在升級任務完成後獨立執行,且可能不會立即開始。 在新版本中,首次備份會複製整個資料庫,因此若資料庫規模較大,此過程可能需要數小時。 請在「備份與還原」中檢查其狀態。 如果操作失敗,請執行按需備份;若仍持續發生錯誤,請聯絡技術支援。 備份失敗並不會使升級還原。

「特定時間點還原」(PITR)無法在主要版本升級之間重播交易。 您可以還原至升級任務開始前的某個時間點,或是升級後的部署完成首次備份之後的某個時間點。 不支援還原至升級完成與升級後備份完成之間的時間點。 該服務會拒絕其中某些還原點,而針對其他還原點的還原操作雖可能被接受,但在還原過程中卻會失敗。 此未受支援的期間包含寫入作業恢復後的這段時間。 在升級後的備份完成之前,即使服務接受了還原請求,還原至最新可用還原點的操作仍可能失敗。

為確保升級後變更仍受 PITR 保護,請將應用程式的寫入操作暫停,直至升級後的備份完成為止。 請在您的應用程式中暫停這些功能。 當寫入操作恢復時,升級程序會重置每個資料庫的 default_transaction_read_only 設定,因此資料庫層級的唯讀設定並不會使寫入操作持續暫停。

升級失敗時,系統不會將備份加入佇列。 在嘗試開始至下次備份完成期間,PITR 可能無法用於累積點數。 若升級失敗後,當 SHOW server_version; 顯示來源版本,且部署環境仍接受寫入操作時,請執行按需備份。 否則,請在執行備份或進行其他變更之前,先聯絡技術支援。

升級前的備份和還原點屬於較早的版本,並仍受保留期限的限制。 如需更多資訊,請參閱 PITR。

API 中( PostgreSQL: )、CLI 中( --skip-backup )以及 Terraform 中( version_upgrade_skip_backup )均不支援「跳過備份」選項。skip_backup 使它們生效的請求均告失敗。 API 和 CLI 會傳回錯誤,且 Terraform 規劃會失敗。

開始之前

請將這些要求同時套用至測試環境和生產環境:

  • 完成 應用程式、擴充功能、複寫準備及 備份準備。

  • 解決 預檢查未能偵測到的狀況,並執行 自我檢查查詢。

  • 請確保每個資料成員所佔用的空間遠低於其可用磁碟空間的一半,以免在重建高可用性成員時發生空間不足的情況。 如需更多資訊,請參閱「升級期間的可用性」。

  • 請確保該部署至少有一份已完成的備份。 在此之前,主控台會停用「升級主要版本」按鈕,且 API 會拒絕該請求。

  • 在唯讀複本部署中,無法使用 IPMVU。 若要升級一個複本,請透過版本升級來將其晉升 為主節點。

  • 將部署中的每個唯讀副本(包括位於其他區域的副本)提升為主動副本或刪除,並等待每項操作完成。 已刪除的複本會持續與該部署保持關聯,直到被永久刪除為止。 只要部署中仍存在任何複本,升級便會因預檢查失敗而無法進行。 請針對從這些複本讀取資料的應用程式進行規劃。 如需更多資訊,請參閱「唯讀複本」與「IPMVU」。

  • 每次只執行一項升級。 當另一個升級任務正在排隊或執行時,該服務會拒絕新的升級請求。

  • 若您將部署的「synchronous_commit」設定為 on,請在提交升級前將其變更為 local。 待該任務顯示為「已完成」後,請將其改回原狀。 若啟用 on,升級失敗可能會導致所有資料庫轉為唯讀狀態,或使提交操作處於等待狀態,直到技術支援人員恢復部署為止。 若執行以下查詢時,結果顯示 on,且來源為 configuration file,則該部署的設定為 on:

    SELECT setting, source
    FROM pg_catalog.pg_settings
    WHERE name = 'synchronous_commit';
    
  • 請從您的部署功能中選擇一個目標。 您可以直接升級至任何顯示為升級路徑的較新版本,無需經過中間版本。 您可以進行配置的版本,未必就是就地升級的目標:

    ibmcloud cdb deployment-capability-show <NAME|CRN> versions
    

    在輸出中,請使用「升級轉換」條目的「to_version」值。

預檢與準備工作

在進入唯讀模式之前,此服務會執行以下檢查。 若檢查失敗,該任務將顯示「失敗」,且部署將維持在當前版本,同時不會阻斷寫入操作。 若任何資料庫的 default_transaction_read_only 設定為 on``,則檢查失敗時,系統也會將所有資料庫的此設定重設,並終止所有客戶端連線。 此任務並未指出哪一項檢查失敗,因此請在提交升級前逐一確認各項內容。

IPMVU 預檢
檢查 在以下情況下通過 您的動作
部署狀態 每個資料成員皆已運行,且每個高可用性成員皆從主節點進行資料串流。 請等待擴展、維護及高可用性 (HA) 成員重建作業完成。 請參閱自助查詢 1。 其他任務雖然通過了這項檢查,但會延遲升級的開始時間。 查看「最近的任務」,或使用 ibmcloud cdb deployment-tasks-list。 如果此檢查持續失敗,請聯絡技術支援。
磁碟空間 每個資料成員最多只會使用其已分配磁碟空間的 90%。 調整磁碟容量,或刪除不再需要的数据。 未使用的邏輯複製槽亦可保留交易日誌。 此檢查允許的使用率上限為 90%,但若要重建高可用性 (HA) 成員,每個資料成員的磁碟使用率必須遠低於其容量的一半。 請參閱「升級期間的可用性」。
CPU、記憶體與磁碟 I/O 針對每個資料成員,主機的 1 分鐘負載平均值不得超過其 CPU 核心數的 90%,且主機記憶體使用率不得超過 90%。 磁碟 I/O 使用率也最多為 90%。 請在系統流量較低時進行升級,或稍後再次提交升級請求。 此服務會測量整個主機的負載與記憶體使用狀況(包含主機上的其他工作負載),並在數秒內對磁碟 I/O 進行採樣。 負載平均值也會將等待磁碟 I/O 的程序納入計算。 因此,其數值可能與您的監控指標有所不同,且擴展部署規模未必能降低這些數值。 如果此檢查持續失敗,請聯絡技術支援。
交易日誌歸檔 歸檔作業並未失敗,且等待歸檔的交易日誌不超過 4 GB。 降低寫入速率,直到積壓資料清除為止。 請參閱 自助查詢 5。 如果某個高可用性 (HA) 成員有待處理的交易日誌(例如在故障轉移後不久),此檢查也會失敗。 如果此檢查持續失敗,請聯絡技術支援。
邏輯複製 不存在任何邏輯複製槽。 在 PostgreSQL 16 及更早版本中,不存在任何邏輯訂閱,包括已停用的訂閱。 移除 插槽。 在 PostgreSQL 16 及更早版本中,請移除 訂閱。 在 PostgreSQL 17 中,請將它們停用。 請參照自檢題目 2 和 3。
唯讀副本與複製客戶端 此部署沒有相關的唯讀副本,且除了高可用性 (HA) 成員之外,沒有其他複製客戶端連線至此部署。 在任何區域和州中,複本都會被計入,包括正在配置中或已斷開連線的複本。 在主控台中列出相關的複本,或使用 ibmcloud cdb deployment-read-replicas。 分別將每一項提升或刪除,並等待每項操作完成。 已刪除的複本在被永久刪除之前仍會被計入總數,儘管清單中已不再顯示該複本。 請參閱「唯讀複本」與「IPMVU」。 請斷開其他複製客戶端的連線。 自檢查詢 1 僅顯示已連線的客戶端。
已準備好的交易 不存在任何已準備好的交易。 請由擁有該交易的管理應用程式或交易管理員來處理已準備好的交易,並在升級完成前阻止建立新的交易。 請勿僅為了通過檢查而提交或回滾這些變更。 請參閱自助查詢 4。
模式匯出 每個資料庫的結構都能順利匯出,且未發生任何錯誤。 若匯出作業因超時或鎖定空間不足而中斷,並不會導致此檢查失敗。 請在從近期備份還原而來的預備部署環境中,對升級進行測試。 此檢查並未驗證目標版本是否能重新建立該資料結構,因此也需解決 預檢查無法偵測到的狀況。 如果此檢查持續失敗,請聯絡技術支援。
升級相容性 PostgreSQL 在主節點及每個高可用性成員上,升級相容性檢查均已通過。 完成 擴建工程的準備工作,包括「pgRouting」檢查。 在 PostgreSQL 17 上,最多保留 10 項訂閱。 請參閱自測題 6、8、9 及 10。

預檢無法偵測到的狀況

預檢無法偵測到以下情況。 其中某些情況會在寫入被阻擋後導致升級失敗。 如果問題出在資料結構上(例如函式或資料庫名稱),在您解決問題之前,每次重試都會以相同的方式失敗。 其他情況會導致該服務將整個資料庫複製到高可用性成員節點上,這會使寫入操作被阻塞更長時間,或者在寫入操作恢復後導致升級失敗。 若在轉換或重新啟動階段發生失敗,亦可能導致高可用性 (HA) 成員處於停止狀態,直至技術支援人員重新啟動它們為止。 在提交升級之前,請先解決或針對每項狀況制定應對方案。

預檢無法偵測到的狀況
條件 效果 要執行的動作
某個資料庫中包含一個名為「UNLOGGED」的資料表。 每個 HA 成員皆已重建,且 UNLOGGED 的內容已重置。 請參閱自助查詢 11。 請參閱 UNLOGGED 中的資料表與序列。
該部署環境執行的是 PostgreSQL 16 或 17,且資料表因批量操作或大量並行插入/更新而擴增。 HA 成員已重建。 規劃重建所需的維護時段及磁碟空間。 請參閱「升級期間的可用性」。
當高可用性 (HA) 成員進行重建時,資料成員會佔用其磁碟空間的大約一半或更多。 重建作業因空間不足而中斷。 寫入操作可能會被阻塞數小時,直到任務失敗為止。 在提交升級請求之前,請調整磁碟容量,直到每個資料成員所佔用的可用磁碟空間均顯著低於 50% 為止。
索引、分區鍵、儲存生成欄位或擴展統計資料會使用帶有字串本體的 LANGUAGE sql 函式,該字串本體會命名位於 pg_catalog 之外且未指定模式的物件。 在索引中,將 ibm_extension 模式命名為,效果相同。 轉換失敗。 請參閱自助查詢 12。 請參閱 索引、分區鍵及生成欄位中的 SQL 函式。
索引或儲存的生成欄位使用 earthdistance 版本 1.1。 轉換失敗。 請參閱自助查詢第 13 項。 參見 earthdistance。
某個視圖、聚合或函數的 SQL 標準本體中,使用了目標版本已移除的系統名稱。 或者,某個函式、角色或資料庫設定使用了已被移除的參數。 轉換失敗。 請參閱自檢題目第 7 題和第 14 題。 請參閱「使用已移除系統名稱的物件」。
anon 已安裝第 2 版。 轉換失敗。 完成「anon」的準備工作。
資料庫名稱包含單引號(' )、反斜線(`` )、等號(= )、換行字元或回車字元。 升級失敗,某些情況下是在寫入操作被阻擋之後發生的。 請參閱自助查詢第 15 項。 請重新命名資料庫,並更新您的連線字串。
資料庫中包含數以千計的資料表和序列,而在 PostgreSQL 14 和 15 中,則包含檢視。 轉換過程因鎖定空間不足而失敗。 請透過自助查詢 16 進行確認,若查詢結果顯示有此需求,請增加 max_locks_per_transaction 的數值。
該部署包含非常多的資料庫、資料表或大型物件。 轉換時間超過了限制。 當資料庫無法使用時,該工作會失敗,或持續處於進行中狀態。 請使用自檢查詢 16 統計資料表和大型物件的數量。 請在從最近的生產環境備份還原而來的測試部署環境中進行排練。 如果預演失敗,請聯絡支援部門。
當升級開始時,寫入活動較高,或是有許多交易日誌正在等待歸檔。 一旦進入唯讀模式,高可用性 (HA) 成員和交易日誌歸檔功能僅有幾分鐘的時間來完成同步。 通過預檢的積壓任務可能需要更長時間才能歸檔,導致升級失敗。 從升級開始直到寫入作業恢復期間,請保持系統負載處於低水平,並在升級前對最近載入的資料表執行 VACUUM 指令。 請使用「升級期間的可用性」中的查詢來檢查複製延遲,並使用自檢查詢 5 來檢查歸檔狀況。
在進入唯讀模式後,寫入操作仍會繼續進行,例如來自唯讀覆寫、維護指令、執行 pg_cron 工作,或 PostgreSQL 17 上已啟用的訂閱。 HA 成員與存檔處理可能無法及時跟上,導致升級失敗。 請在提交升級之前停止這些寫入操作,詳情請參閱「升級期間的可用性」一節。
客戶在預檢查完成後準備一筆交易。PREPARE TRANSACTION 在唯讀模式下仍可正常運作。 在寫入被阻塞期間,升級失敗。 若在 PostgreSQL 停止運作前不久才準備好的交易,可能會導致轉換失敗。 在任務顯示為「已完成」之前,請暫停所有使用兩階段提交的客戶端。 請參閱自助查詢 4。
在升級過程中,有個複製客戶端連線了。 它所建立的時槽不會被保留,且在資料庫不可用期間,升級可能會失敗或陷入停滯。 請保持複製客戶端處於斷開連接狀態,直到該任務顯示為「已完成」。 請參照自助查詢 1 和 2 進行確認。
在寫入恢復後,會執行一項持續的大量載入作業。 在恢復寫入後,該任務會失敗,而部署將繼續執行目標版本,直到支援團隊完成升級為止。 在任務顯示為「已完成」之前,請避免進行批量載入。
此部署的「synchronous_commit」設定為 on。 若升級失敗,所有資料庫都將轉為唯讀狀態,直到技術支援團隊恢復部署為止。 請依照「開始之前」中的說明,將其變更為 local。
當您從 PostgreSQL 16 或更早版本升級至 17 或更新版本時,若某個索引、實體化檢視或擴展統計資料使用了未設定 search_path 的函數,則會發生此情況。 升級後,ANALYZE、REINDEX、CLUSTER、VACUUM FULL 以及 REFRESH MATERIALIZED VIEW 針對這些物件可能會發生錯誤。 請參閱自助查詢第 17 項。 請參閱 索引、分區鍵及生成欄位中的 SQL 函式。

在提交升級請求與任務完成之間,請勿變更模式、擴充功能、資料庫、邏輯複製槽或訂閱。

自行檢查準備狀況

在提交升級之前,請以 admin 使用者身分,透過 psql 執行以下查詢。 這些功能適用於 PostgreSQL 14 至 18 版。 查詢 1 至 7 以及查詢 15 涵蓋整個部署,因此只需在任一資料庫中執行一次即可。 請在每個資料庫中執行其餘的查詢。

  1. 複製連線。 預期每個高可用性 (HA) 成員會佔一行,其數量等於資料成員的總數減一,每行的狀態皆為 streaming。 任何其他列皆為唯讀副本或另一個複製客戶端。 若出現名為「pg_basebackup」的資料列,表示該服務正在將資料庫複製到高可用性 (HA) 成員或唯讀副本上。 請等待複製完成,然後再次執行該查詢。

    SELECT application_name, client_addr, state
    FROM pg_catalog.pg_stat_replication
    ORDER BY application_name;
    
  2. 邏輯複製槽。 別指望會有爭執。

    SELECT slot_name, plugin, database, active
    FROM pg_catalog.pg_replication_slots
    WHERE slot_type = 'logical';
    
  3. 邏輯訂閱。 在 PostgreSQL 16 及更早版本中,預期不會有任何資料列。 在 PostgreSQL 17 中,預期每行「subenabled」欄位中的值皆為 f。

    SELECT d.datname AS database_name, s.subname, s.subenabled
    FROM pg_catalog.pg_subscription AS s
    JOIN pg_catalog.pg_database AS d ON d.oid = s.subdbid;
    
  4. 已準備好的交易。 別指望會有爭執。

    SELECT gid, owner, database, prepared
    FROM pg_catalog.pg_prepared_xacts;
    
  5. 交易日誌歸檔。 預期 last_failed_time 為空或小於 last_archived_time``,而 waiting_files 為 0 或接近 0。 即使通過預檢的積壓工作,在進入唯讀模式後,其規模仍可能過大而無法歸檔。

    SELECT failed_count, last_failed_time, last_archived_time
    FROM pg_catalog.pg_stat_archiver;
    
    SELECT count(*) AS waiting_files,
           pg_catalog.pg_size_pretty(count(*) * pg_catalog.pg_size_bytes(pg_catalog.current_setting('wal_segment_size'))) AS waiting_size
    FROM pg_catalog.pg_ls_archive_statusdir()
    WHERE name LIKE '%.ready';
    
  6. 資料庫連線設定。 別指望會有爭執。 刪除一個已列出的資料庫,其 datconnlimit 為 -2,因為該 無效。 對於清單中列出的任何其他資料庫,請允許連線或將其刪除。 若查詢結果顯示「template0」,請聯絡技術支援。

    SELECT datname, datallowconn, datconnlimit
    FROM pg_catalog.pg_database
    WHERE (datname <> 'template0' AND (NOT datallowconn OR datconnlimit = -2))
       OR (datname = 'template0' AND datallowconn);
    
  7. 角色與資料庫設定。 請確保 setconfig 中的每個參數在目標版本中均存在。 將目標版本已移除或重新命名的參數重設為原始值,並在升級後設定其替代值。 這也適用於由擴充功能所定義的參數,其名稱中包含句點。 請確保沒有任何角色將 default_transaction_read_only 設定為偽值,例如 off、` `false、 no 或 ` `0。 請記錄每個將 default_transaction_read_only`` 設為 true 的資料庫,因為升級過程會重置此設定。 自檢查詢 14 會檢查各項功能的設定。

    SELECT r.rolname AS role_name, d.datname AS database_name, s.setconfig
    FROM pg_catalog.pg_db_role_setting AS s
    LEFT JOIN pg_catalog.pg_roles AS r ON r.oid = s.setrole
    LEFT JOIN pg_catalog.pg_database AS d ON d.oid = s.setdatabase;
    
  8. PostgreSQL 無法升級的欄位資料類型。 別指望會有爭執。 此查詢還會列出系統複合型別的欄位,以及基於這些型別建構的域、陣列、複合型別和範圍的欄位。 base_type 欄位會顯示阻礙升級的類型。 aclitem 型號僅會阻擋從 PostgreSQL 14 或 15 升級至 16 或更新版本的操作。

    WITH RECURSIVE problem_types (type_oid, base_type) AS (
      SELECT t.oid, t.typname::text
      FROM pg_catalog.pg_type AS t
      WHERE t.typnamespace = 'pg_catalog'::pg_catalog.regnamespace
        AND t.typname IN ('regcollation', 'regconfig', 'regdictionary', 'regnamespace',
                          'regoper', 'regoperator', 'regproc', 'regprocedure', 'aclitem')
      UNION ALL
      SELECT t.oid, 'system composite type ' || t.oid::pg_catalog.regtype::text
      FROM pg_catalog.pg_type AS t
      LEFT JOIN pg_catalog.pg_namespace AS n ON n.oid = t.typnamespace
      WHERE t.typtype = 'c'
        AND (t.oid < 16384 OR n.nspname = 'information_schema')
      UNION ALL
      SELECT derived.type_oid, derived.base_type
      FROM (
        WITH found AS (SELECT type_oid, base_type FROM problem_types)
        SELECT t.oid AS type_oid, f.base_type
        FROM pg_catalog.pg_type AS t
        JOIN found AS f ON t.typtype = 'd' AND t.typbasetype = f.type_oid
        UNION ALL
        SELECT t.oid, f.base_type
        FROM pg_catalog.pg_type AS t
        JOIN found AS f ON t.typtype = 'b' AND t.typelem = f.type_oid
        UNION ALL
        SELECT t.oid, f.base_type
        FROM pg_catalog.pg_type AS t
        JOIN pg_catalog.pg_class AS c ON c.reltype = t.oid
        JOIN pg_catalog.pg_attribute AS a ON a.attrelid = c.oid AND NOT a.attisdropped
        JOIN found AS f ON a.atttypid = f.type_oid
        WHERE t.typtype = 'c'
        UNION ALL
        SELECT t.oid, f.base_type
        FROM pg_catalog.pg_type AS t
        JOIN pg_catalog.pg_range AS r ON r.rngtypid = t.oid
        JOIN found AS f ON r.rngsubtype = f.type_oid
        WHERE t.typtype = 'r'
      ) AS derived
    )
    SELECT DISTINCT n.nspname AS schema_name, c.relname AS relation_name, a.attname AS column_name,
           a.atttypid::pg_catalog.regtype AS data_type, p.base_type
    FROM pg_catalog.pg_attribute AS a
    JOIN pg_catalog.pg_class AS c ON c.oid = a.attrelid
    JOIN pg_catalog.pg_namespace AS n ON n.oid = c.relnamespace
    JOIN problem_types AS p ON p.type_oid = a.atttypid
    WHERE a.attnum > 0
      AND NOT a.attisdropped
      AND c.relkind IN ('r', 'm', 'i')
      AND n.nspname NOT IN ('pg_catalog', 'information_schema')
      AND n.nspname !~ '^pg_toast_temp_|^pg_temp_'
    ORDER BY 1, 2, 3;
    
  9. 繼承了父表中未設有 NOT NULL 限制條件的欄位。 別指望會有爭執。 若要鎖定已列出的欄位,資料表擁有者需執行 ALTER TABLE <table_name> ALTER COLUMN <column_name> SET NOT NULL;。

    SELECT n.nspname AS schema_name, c.relname AS table_name, child.attname AS column_name
    FROM pg_catalog.pg_inherits AS i
    JOIN pg_catalog.pg_attribute AS child ON child.attrelid = i.inhrelid
    JOIN pg_catalog.pg_attribute AS parent
      ON parent.attrelid = i.inhparent AND parent.attname = child.attname
    JOIN pg_catalog.pg_class AS c ON c.oid = i.inhrelid
    JOIN pg_catalog.pg_namespace AS n ON n.oid = c.relnamespace
    WHERE parent.attnum > 0
      AND parent.attnotnull
      AND NOT child.attnotnull
      AND NOT child.attisdropped;
    
  10. 已安裝的擴充功能。 請完成「延伸準備」。 接著,請確認所有剩餘的擴充功能在目標版本中皆可使用,例如在該版本的預發布環境中。

    SELECT extname, extversion
    FROM pg_catalog.pg_extension
    ORDER BY extname;
    
  11. UNLOGGED 資料表與序列。 這些資料在升級過程中無法保留,而清單中的表格會導致服務必須重建每個高可用性成員。 在進行升級之前,請參閱 UNLOGGED 中的資料表與序列。

    SELECT n.nspname AS schema_name, c.relname AS relation_name, c.relkind
    FROM pg_catalog.pg_class AS c
    JOIN pg_catalog.pg_namespace AS n ON n.oid = c.relnamespace
    WHERE c.relpersistence = 'u'
      AND c.relkind IN ('r', 'S');
    
  12. 可能導致轉換失敗的 SQL 函數。 別指望會有爭執。 此查詢會列出由索引、部分索引判別式、分區鍵、儲存生成欄位或擴展統計資料所使用的、具有字串本體的 LANGUAGE sql 函數。 其後接續透過運算子、網域檢查約束以及具有 SQL 標準本體的函式所進行的呼叫。 關於每項列出的函數,請 參閱索引、分區鍵及生成欄位中的 SQL 函數。

    WITH RECURSIVE uses (refclassid, refobjid, used_by) AS (
      SELECT d.refclassid, d.refobjid,
             CASE WHEN c.relkind = 'p' THEN 'partition key of ' ELSE 'index ' END
               || c.oid::pg_catalog.regclass::text
      FROM pg_catalog.pg_depend AS d
      JOIN pg_catalog.pg_class AS c
        ON d.classid = 'pg_catalog.pg_class'::pg_catalog.regclass
       AND c.oid = d.objid
      WHERE c.relkind IN ('i', 'I') OR (c.relkind = 'p' AND d.objsubid = 0)
      UNION
      SELECT d.refclassid, d.refobjid,
             'generated column ' || a.attname || ' of ' || a.attrelid::pg_catalog.regclass::text
      FROM pg_catalog.pg_depend AS d
      JOIN pg_catalog.pg_attrdef AS ad
        ON d.classid = 'pg_catalog.pg_attrdef'::pg_catalog.regclass
       AND ad.oid = d.objid
      JOIN pg_catalog.pg_attribute AS a
        ON a.attrelid = ad.adrelid
       AND a.attnum = ad.adnum
      WHERE a.attgenerated = 's'
      UNION
      SELECT d.refclassid, d.refobjid,
             'generated column ' || a.attname || ' of ' || a.attrelid::pg_catalog.regclass::text
      FROM pg_catalog.pg_depend AS d
      JOIN pg_catalog.pg_attribute AS a
        ON d.classid = 'pg_catalog.pg_class'::pg_catalog.regclass
       AND a.attrelid = d.objid
       AND a.attnum = d.objsubid
      WHERE a.attgenerated = 's'
      UNION
      SELECT d.refclassid, d.refobjid, 'statistics ' || s.stxname || ' on ' || s.stxrelid::pg_catalog.regclass::text
      FROM pg_catalog.pg_depend AS d
      JOIN pg_catalog.pg_statistic_ext AS s
        ON d.classid = 'pg_catalog.pg_statistic_ext'::pg_catalog.regclass
       AND s.oid = d.objid
    ), used (fn, used_by) AS (
      SELECT x.fn, u.used_by
      FROM uses AS u
      CROSS JOIN LATERAL (
        SELECT u.refobjid AS fn
        WHERE u.refclassid = 'pg_catalog.pg_proc'::pg_catalog.regclass
        UNION ALL
        SELECT o.oprcode::pg_catalog.oid
        FROM pg_catalog.pg_operator AS o
        WHERE u.refclassid = 'pg_catalog.pg_operator'::pg_catalog.regclass
          AND o.oid = u.refobjid
        UNION ALL
        SELECT dc.refobjid
        FROM pg_catalog.pg_constraint AS con
        JOIN pg_catalog.pg_depend AS dc
          ON dc.classid = 'pg_catalog.pg_constraint'::pg_catalog.regclass
         AND dc.objid = con.oid
         AND dc.refclassid = 'pg_catalog.pg_proc'::pg_catalog.regclass
        WHERE u.refclassid = 'pg_catalog.pg_type'::pg_catalog.regclass
          AND con.contypid = u.refobjid
      ) AS x
      UNION
      SELECT x.fn, u.used_by
      FROM used AS u
      JOIN pg_catalog.pg_proc AS p
        ON p.oid = u.fn
       AND p.prosqlbody IS NOT NULL
       AND p.proconfig IS NULL
       AND NOT p.prosecdef
      JOIN pg_catalog.pg_depend AS d
        ON d.classid = 'pg_catalog.pg_proc'::pg_catalog.regclass
       AND d.objid = u.fn
      CROSS JOIN LATERAL (
        SELECT d.refobjid AS fn
        WHERE d.refclassid = 'pg_catalog.pg_proc'::pg_catalog.regclass
        UNION ALL
        SELECT o.oprcode::pg_catalog.oid
        FROM pg_catalog.pg_operator AS o
        WHERE d.refclassid = 'pg_catalog.pg_operator'::pg_catalog.regclass
          AND o.oid = d.refobjid
      ) AS x
    )
    SELECT DISTINCT u.fn::pg_catalog.regprocedure AS function_name, u.used_by
    FROM used AS u
    JOIN pg_catalog.pg_proc AS p ON p.oid = u.fn
    JOIN pg_catalog.pg_language AS l ON l.oid = p.prolang
    WHERE l.lanname = 'sql'
      AND p.prosqlbody IS NULL
      AND p.proconfig IS NULL
      AND NOT p.prosecdef
      AND p.pronamespace <> 'pg_catalog'::pg_catalog.regnamespace
      AND NOT EXISTS (SELECT 1
                      FROM pg_catalog.pg_depend AS e
                      WHERE e.classid = 'pg_catalog.pg_proc'::pg_catalog.regclass
                        AND e.objid = p.oid
                        AND e.deptype = 'e')
    ORDER BY 1, 2;
    
  13. 直接或透過具有 SQL 標準本體的函數,使用 earthdistance 版本 1.1 的索引及儲存生成欄位。 別指望會有爭執。 關於每個列出的項目,請參閱 earthdistance。

    WITH RECURSIVE used (fn, via, used_by) AS (
      SELECT d.refobjid, d.refobjid, 'index ' || c.oid::pg_catalog.regclass::text
      FROM pg_catalog.pg_depend AS d
      JOIN pg_catalog.pg_class AS c
        ON d.classid = 'pg_catalog.pg_class'::pg_catalog.regclass
       AND c.oid = d.objid
       AND c.relkind IN ('i', 'I')
      WHERE d.refclassid = 'pg_catalog.pg_proc'::pg_catalog.regclass
      UNION
      SELECT d.refobjid, d.refobjid,
             'generated column ' || a.attname || ' of ' || a.attrelid::pg_catalog.regclass::text
      FROM pg_catalog.pg_depend AS d
      LEFT JOIN pg_catalog.pg_attrdef AS ad
        ON d.classid = 'pg_catalog.pg_attrdef'::pg_catalog.regclass
       AND ad.oid = d.objid
      JOIN pg_catalog.pg_attribute AS a
        ON a.attgenerated = 's'
       AND ((a.attrelid = ad.adrelid AND a.attnum = ad.adnum)
            OR (d.classid = 'pg_catalog.pg_class'::pg_catalog.regclass
                AND a.attrelid = d.objid
                AND a.attnum = d.objsubid))
      WHERE d.refclassid = 'pg_catalog.pg_proc'::pg_catalog.regclass
      UNION
      SELECT d.refobjid, u.via, u.used_by
      FROM used AS u
      JOIN pg_catalog.pg_proc AS p
        ON p.oid = u.fn
       AND p.prosqlbody IS NOT NULL
       AND p.proconfig IS NULL
      JOIN pg_catalog.pg_depend AS d
        ON d.classid = 'pg_catalog.pg_proc'::pg_catalog.regclass
       AND d.objid = u.fn
       AND d.refclassid = 'pg_catalog.pg_proc'::pg_catalog.regclass
    )
    SELECT e.extversion, u.via::pg_catalog.regprocedure AS used_function, u.used_by
    FROM used AS u
    JOIN pg_catalog.pg_depend AS m
      ON m.classid = 'pg_catalog.pg_proc'::pg_catalog.regclass
     AND m.objid = u.fn
     AND m.refclassid = 'pg_catalog.pg_extension'::pg_catalog.regclass
     AND m.deptype = 'e'
    JOIN pg_catalog.pg_extension AS e ON e.oid = m.refobjid
    JOIN pg_catalog.pg_proc AS p ON p.oid = u.fn
    JOIN pg_catalog.pg_language AS l ON l.oid = p.prolang
    WHERE e.extname = 'earthdistance'
      AND e.extversion IN ('1.0', '1.1')
      AND l.lanname = 'sql'
      AND p.proconfig IS NULL
    ORDER BY 2, 3;
    
  14. 使用系統目錄名稱或配置參數的檢視、實體化檢視、聚合及函數,而這些名稱或參數已在後續版本的 PostgreSQL 中移除。 removed_in 欄位顯示的是未包含名稱的第一個版本。 若 removed_in 的版本等於或低於您的目標版本,則預期不會出現任何資料列。 名稱可能會與非目錄參考的文字相符,因此請逐一檢視清單中的每個項目。 請參閱「使用已移除系統名稱的物件」。

    WITH removed (relation_name, identifier, removed_in) AS (
      VALUES (NULL, 'pg_is_in_backup', 15), (NULL, 'pg_backup_start_time', 15),
             (NULL, 'pg_start_backup', 15), (NULL, 'pg_stop_backup', 15),
             ('pg_database', 'datlastsysoid', 15),
             (NULL, 'force_parallel_mode', 16),
             ('pg_stat_bgwriter', 'checkpoints_timed', 17), ('pg_stat_bgwriter', 'checkpoints_req', 17),
             ('pg_stat_bgwriter', 'checkpoint_write_time', 17), ('pg_stat_bgwriter', 'checkpoint_sync_time', 17),
             ('pg_stat_bgwriter', 'buffers_checkpoint', 17), ('pg_stat_bgwriter', 'buffers_backend', 17),
             ('pg_stat_bgwriter', 'buffers_backend_fsync', 17),
             (NULL, 'pg_stat_get_bgwriter_timed_checkpoints', 17),
             (NULL, 'pg_stat_get_bgwriter_requested_checkpoints', 17),
             (NULL, 'pg_stat_get_checkpoint_write_time', 17), (NULL, 'pg_stat_get_checkpoint_sync_time', 17),
             (NULL, 'pg_stat_get_bgwriter_buf_written_checkpoints', 17),
             (NULL, 'pg_stat_get_buf_written_backend', 17), (NULL, 'pg_stat_get_buf_fsync_backend', 17),
             ('pg_stat_progress_vacuum', 'max_dead_tuples', 17),
             ('pg_stat_progress_vacuum', 'num_dead_tuples', 17),
             ('pg_database', 'daticulocale', 17), ('pg_collation', 'colliculocale', 17),
             ('element_types', 'domain_default', 17),
             (NULL, 'interval_accum', 17), (NULL, 'interval_accum_inv', 17), (NULL, 'interval_combine', 17),
             ('pg_stat_wal', 'wal_write', 18), ('pg_stat_wal', 'wal_sync', 18),
             ('pg_stat_wal', 'wal_write_time', 18), ('pg_stat_wal', 'wal_sync_time', 18),
             ('pg_stat_io', 'op_bytes', 18), ('pg_backend_memory_contexts', 'parent', 18),
             ('pg_attribute', 'attcacheoff', 18)
    ), definitions (object_name, definition) AS (
      SELECT 'view ' || c.oid::pg_catalog.regclass::text, pg_catalog.pg_get_viewdef(c.oid)
      FROM pg_catalog.pg_class AS c
      WHERE c.relkind IN ('v', 'm')
        AND c.relnamespace NOT IN ('pg_catalog'::pg_catalog.regnamespace,
                                   'information_schema'::pg_catalog.regnamespace)
      UNION ALL
      SELECT 'function ' || p.oid::pg_catalog.regprocedure::text,
             pg_catalog.concat_ws(' ', pg_catalog.pg_get_function_sqlbody(p.oid),
                                  pg_catalog.array_to_string(p.proconfig, ' '))
      FROM pg_catalog.pg_proc AS p
      WHERE (p.prosqlbody IS NOT NULL OR p.proconfig IS NOT NULL)
        AND p.pronamespace NOT IN ('pg_catalog'::pg_catalog.regnamespace,
                                   'information_schema'::pg_catalog.regnamespace)
      UNION ALL
      SELECT 'aggregate ' || a.aggfnoid::pg_catalog.regprocedure::text,
             pg_catalog.concat_ws(' ', a.aggtransfn, a.aggfinalfn, a.aggcombinefn,
                                  a.aggmtransfn, a.aggminvtransfn, a.aggmfinalfn)
      FROM pg_catalog.pg_aggregate AS a
      JOIN pg_catalog.pg_proc AS p ON p.oid = a.aggfnoid
      WHERE p.pronamespace NOT IN ('pg_catalog'::pg_catalog.regnamespace,
                                   'information_schema'::pg_catalog.regnamespace)
    )
    SELECT d.object_name, r.identifier, r.removed_in
    FROM definitions AS d
    JOIN removed AS r
      ON d.definition ~ ('\m' || r.identifier || '\M')
     AND (r.relation_name IS NULL OR d.definition ~ ('\m' || r.relation_name || '\M'))
    ORDER BY 3, 1, 2;
    
  15. 升級程序無法使用的資料庫名稱。 別指望會有爭執。 若要修復清單中的資料庫,其擁有者必須先連線至另一個資料庫並執行,且 ALTER DATABASE "<database_name>" RENAME TO <new_name>; 在執行此操作時,被重新命名之資料庫不得有任何連線中的工作階段。 擁有者還必須具備 CREATEDB 屬性。 接著,請更新所有會連線至該資料庫的應用程式。

    SELECT datname
    FROM pg_catalog.pg_database
    WHERE pg_catalog.strpos(datname, '''') > 0
       OR pg_catalog.strpos(datname, pg_catalog.chr(92)) > 0
       OR pg_catalog.strpos(datname, '=') > 0
       OR pg_catalog.strpos(datname, pg_catalog.chr(10)) > 0
       OR pg_catalog.strpos(datname, pg_catalog.chr(13)) > 0
    ORDER BY datname;
    
  16. 升級所鎖定的關聯、大型物件,以及部署的鎖定容量。 將值最高的四個資料庫的 locked_relations 相加。 在 PostgreSQL 14 和 15 中,locked_relations 包含檢視與實體化檢視,因為升級過程也會鎖定這些項目。 若總數超過 lock_capacity,則增加 max_locks_per_transaction,直到 lock_capacity 超過總數為止。 此變更會重新啟動資料庫,因此請在提交升級之前進行此變更。 若表數量眾多或物件體積龐大,也會延長轉換時間,因此請使用實際的資料結構和資料進行升級演練。

    SELECT pg_catalog.current_database() AS database_name,
           (SELECT pg_catalog.count(*)
            FROM pg_catalog.pg_class AS c
            WHERE (c.relkind IN ('r', 'p', 'S')
                   OR (c.relkind IN ('v', 'm')
                       AND pg_catalog.current_setting('server_version_num')::integer < 160000))
              AND c.relnamespace NOT IN ('pg_catalog'::pg_catalog.regnamespace,
                                         'information_schema'::pg_catalog.regnamespace)) AS locked_relations,
           (SELECT pg_catalog.count(*)
            FROM pg_catalog.pg_largeobject_metadata) AS large_objects,
           pg_catalog.current_setting('max_locks_per_transaction')::integer
             * (pg_catalog.current_setting('max_connections')::integer
                + pg_catalog.current_setting('max_prepared_transactions')::integer) AS lock_capacity;
    
  17. 未設定 search_path 且由索引、實體化檢視及擴充統計資料所使用的函式。 該查詢會依序執行運算子、域檢查約束以及具有 SQL 標準本體的函數。 若您是從 PostgreSQL 16 或更早版本升級至 PostgreSQL 17 或更新版本,請執行此查詢。 若某個已登錄函式的本體中,將 pg_catalog 以外的物件以不帶其模式的方式命名,則升級後維護指令將會失敗。 一個函式僅在其本體,以及它所呼叫的每個函式,皆以其模式為 pg_catalog 外部的所有物件命名時,才不受影響。 對於其他列出的函式,其擁有者會新增一個 search_path 設定,詳情請參閱「 索引、分區鍵及產生欄位中的 SQL 函式」 一節。

    WITH RECURSIVE refreshed (relid, used_by) AS (
      SELECT c.oid, c.oid::pg_catalog.regclass
      FROM pg_catalog.pg_class AS c
      WHERE c.relkind = 'm'
      UNION
      SELECT v.oid, f.used_by
      FROM refreshed AS f
      JOIN pg_catalog.pg_rewrite AS r ON r.ev_class = f.relid
      JOIN pg_catalog.pg_depend AS d
        ON d.classid = 'pg_catalog.pg_rewrite'::pg_catalog.regclass
       AND d.objid = r.oid
       AND d.refclassid = 'pg_catalog.pg_class'::pg_catalog.regclass
      JOIN pg_catalog.pg_class AS v ON v.oid = d.refobjid AND v.relkind = 'v'
    ), refs (refclassid, refobjid, used_by) AS (
      SELECT d.refclassid, d.refobjid, c.oid::pg_catalog.regclass
      FROM pg_catalog.pg_depend AS d
      JOIN pg_catalog.pg_class AS c ON c.oid = d.objid AND c.relkind IN ('i', 'I')
      WHERE d.classid = 'pg_catalog.pg_class'::pg_catalog.regclass
      UNION
      SELECT d.refclassid, d.refobjid, f.used_by
      FROM refreshed AS f
      JOIN pg_catalog.pg_rewrite AS r ON r.ev_class = f.relid
      JOIN pg_catalog.pg_depend AS d
        ON d.classid = 'pg_catalog.pg_rewrite'::pg_catalog.regclass
       AND d.objid = r.oid
      UNION
      SELECT d.refclassid, d.refobjid, s.stxrelid::pg_catalog.regclass
      FROM pg_catalog.pg_depend AS d
      JOIN pg_catalog.pg_statistic_ext AS s ON s.oid = d.objid
      WHERE d.classid = 'pg_catalog.pg_statistic_ext'::pg_catalog.regclass
    ), used (fn, used_by) AS (
      SELECT x.fn, r.used_by
      FROM refs AS r
      CROSS JOIN LATERAL (
        SELECT r.refobjid AS fn
        WHERE r.refclassid = 'pg_catalog.pg_proc'::pg_catalog.regclass
        UNION ALL
        SELECT o.oprcode::pg_catalog.oid
        FROM pg_catalog.pg_operator AS o
        WHERE r.refclassid = 'pg_catalog.pg_operator'::pg_catalog.regclass
          AND o.oid = r.refobjid
        UNION ALL
        SELECT dc.refobjid
        FROM pg_catalog.pg_constraint AS con
        JOIN pg_catalog.pg_depend AS dc
          ON dc.classid = 'pg_catalog.pg_constraint'::pg_catalog.regclass
         AND dc.objid = con.oid
         AND dc.refclassid = 'pg_catalog.pg_proc'::pg_catalog.regclass
        WHERE r.refclassid = 'pg_catalog.pg_type'::pg_catalog.regclass
          AND con.contypid = r.refobjid
      ) AS x
      UNION
      SELECT x.fn, u.used_by
      FROM used AS u
      JOIN pg_catalog.pg_proc AS p
        ON p.oid = u.fn
       AND p.prosqlbody IS NOT NULL
       AND NOT EXISTS (SELECT 1
                       FROM pg_catalog.unnest(p.proconfig) AS setting
                       WHERE setting LIKE 'search\_path=%')
      JOIN pg_catalog.pg_depend AS d
        ON d.classid = 'pg_catalog.pg_proc'::pg_catalog.regclass
       AND d.objid = u.fn
      CROSS JOIN LATERAL (
        SELECT d.refobjid AS fn
        WHERE d.refclassid = 'pg_catalog.pg_proc'::pg_catalog.regclass
        UNION ALL
        SELECT o.oprcode::pg_catalog.oid
        FROM pg_catalog.pg_operator AS o
        WHERE d.refclassid = 'pg_catalog.pg_operator'::pg_catalog.regclass
          AND o.oid = d.refobjid
      ) AS x
    )
    SELECT DISTINCT p.oid::pg_catalog.regprocedure AS function_name, u.used_by
    FROM used AS u
    JOIN pg_catalog.pg_proc AS p ON p.oid = u.fn
    JOIN pg_catalog.pg_language AS l ON l.oid = p.prolang
    WHERE l.lanname NOT IN ('c', 'internal')
      AND p.prosqlbody IS NULL
      AND p.pronamespace NOT IN ('pg_catalog'::pg_catalog.regnamespace,
                                 'information_schema'::pg_catalog.regnamespace)
      AND NOT EXISTS (SELECT 1
                      FROM pg_catalog.unnest(p.proconfig) AS setting
                      WHERE setting LIKE 'search\_path=%')
      AND NOT EXISTS (SELECT 1
                      FROM pg_catalog.pg_depend AS e
                      WHERE e.classid = 'pg_catalog.pg_proc'::pg_catalog.regclass
                        AND e.objid = p.oid
                        AND e.deptype = 'e')
    ORDER BY 1, 2;
    

通過這些檢查,並不保證升級會成功,也不保證您的應用程式與目標版本相容。 只有在分階段部署中的預演階段才會執行完整的轉換。

規劃升級時段

請利用預演來估算維護時段。 轉換時間主要取決於資料庫和物件的數量。 重建高可用性 (HA) 成員所需的時間取決於資料庫的大小。 工作負載和交易日誌的體積會影響檢查和補救作業。 請預留足夠的時間來完成整個升級任務,而不僅僅是寫入操作被阻塞的時間。

「開始過期時間」設定了排隊中的升級作業最晚可開始的時間。 預設值為請求後 5 分鐘,您可將其設定為最多 24 小時後。 正在執行的操作(例如備份)以及先前排入佇列的請求,都會延遲開始時間。 如果升級在到期時間之前未開始,則不會執行,且其任務狀態將顯示為「已過期」。 到期並不會中斷已開始的升級程序。 舉例來說,某個排隊中的請求將於 UTC 時間 22:30 過期。 一項於 22:25 UTC 開始的任務,可能會持續到該時間之後。

在升級執行期間,其他與該部署相關的請求將暫停處理,直至升級完成為止。 這些包括手動與自動擴展、設定變更、使用者與密碼變更、允許的 IP 位址變更,以及備份。 當升級任務處於排程或執行中時,請勿刪除該部署。

在任務完成之前,請勿建立唯讀複本。 該服務不會阻擋此類請求。 若您建立一個,升級可能會在預檢階段失敗,或者新的複本無法從已升級的部署中進行複製。 刪除此複本,並在任務完成後建立一個新的複本。

在使用者介面中升級

  1. 建立並驗證一個 隨選備份。 此升級版本不包含此功能。
  2. 在部署的「概覽」頁面上,點選「升級主要版本」。
  3. 在「指引」步驟中,請詳閱指引,選取「我已閱讀指引,並準備好進行升級」,然後按一下「下一步」。 如需瞭解何時無法進行讀取和寫入操作,請參閱「升級期間的可用性」。
  4. 在「升級至版本」中,請選擇目標版本。 若有多個目標可供選擇,清單預設會選取最新的那個。 此步驟中的「讀取複本」通知已過時。 只要部署中仍存在任何唯讀副本,升級便會因預檢失敗而無法進行;因此,請在升級前將所有副本提升為主副本或刪除。
  5. 在「升級開始的過期時間」中,請選擇請求可等待開始的時間長度。 預設值為 5 分鐘。
  6. 按一下升級。 當請求處於等待或執行狀態時,「概覽」頁面的「版本」列會顯示「升級已排入佇列」或「升級中」。
  7. 在「最近的任務」中監控該任務。 一旦寫入作業恢復,請依照「升級完成後」章節所述的方式重新整理統計資料。 當任務顯示為「已完成」時,請完成該區段中剩餘的步驟。 若顯示「失敗」,請參閱「疑難排解」。 如果顯示「已過期」,表示升級尚未開始,您可以設定較晚的到期日期後再次提交。

透過 API 升級

向 /deployments/{id}/version 端點發送一個 PATCH 請求。 將 version 設定為目標主要版本,並透過 expiration_datetime 查詢參數設定有效期限起始時間:

curl -X PATCH \
  'https://api.{region}.databases.cloud.ibm.com/v5/ibm/deployments/{id}/version?expiration_datetime=<EXPIRATION_TIME>' \
  -H 'Authorization: Bearer <IAM_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"version": "18"}'

請將 <EXPIRATION_TIME> 替換為 ISO 8601 格式的 UTC 時間(例如 2026-11-03T22:30:00Z),時間範圍為請求後 5 分鐘至 24 小時。 若未指定 ` `expiration_datetime,則該請求若在 5 分鐘內未開始執行,將會過期。

若請求成功,則會傳回一個任務。 已接受的請求並不代表升級已完成。 請使用該任務 ID 並透過「取得任務資訊」來監控升級進度。 若要列出可用的目標,請使用具備「versions」功能的 部署來「探索」功能資訊。 有關所有參數的詳細資訊,請參閱 API 參考 手冊。

透過 CLI 升級

請使用 0.20.0 或更新版本的 Cloud Databases CLI 外掛程式。 請使用 --expire-in 或 --expire-at`` 設定有效期起始時間,範圍為請求後 5 分鐘至 24 小時。 預設值為 5 分鐘。

ibmcloud cdb deployment-version-upgrade <NAME|CRN> <TARGET_VERSION> --expire-in 1h --nowait

若未指定 --nowait,該指令會等待直到任務完成或失敗為止。 如果升級在開始前已過期,則不會返回任何結果,因此請在腳本中使用 ` `--nowait` `。 若使用 ` `--nowait,則在服務接受請求後,該命令便會返回。 使用 deployment-tasks-list:

ibmcloud cdb deployment-tasks-list <NAME|CRN>

針對所有參數,請執行 ibmcloud cdb deployment-version-upgrade --help。

透過 Terraform 進行升級

請使用 IBM Cloud® Terraform 提供者版本 1.79.2 或更新版本。 將「version」設定為可用的目標,檢視計畫,並加以執行。 若目標無法進行就地升級,則該計畫將失敗。

請將資源的更新超時設定為足以涵蓋整個升級過程的時間,且至少為 5 分鐘。 該服務提供者亦將此超時設定(最長 24 小時)作為有效期起始時間。 因此,排入佇列的升級作業可在超時期限屆滿前隨時開始執行。 請在沒有任何備份或其他作業正在執行或排入佇列時套用此變更,以便升級能立即開始。 若在升級開始後,套用程序超時,升級仍會繼續進行。 若超時期限屆滿時,升級仍處於排程狀態,則該升級將失效且不會執行。 請等待任務完成後,再重新執行 terraform plan 或 terraform apply。

如果升級任務失敗,請在再次執行「terraform apply」之前,先完成「疑難排解」步驟。 每當部署仍回報原始版本時,Terraform 便會再次提交升級請求。

在 Terraform 外部進行升級後,請將 version 設定為新版本,或從配置中移除 version 。 Terraform 以外的升級包括使用者介面 (UI)、命令列介面 (CLI) 或 API 的升級,以及 強制升級。 在您更新配置之前,所有包含該部署的 terraform plan 及 terraform apply 請求都會失敗,這將導致無法對同一配置中的其他資源進行變更。 此錯誤與 Version 14 is not a valid upgrade version 或 No available upgrade versions for version 18 中的錯誤類似。

PostgreSQL 不支援 version_upgrade_skip_backup 參數。 如需更多資訊,請參閱 資料庫資源參考手冊。

升級後

一旦恢復寫入操作,請確保優化器的統計資料已完整。 請勿等待任務完成。 當 SHOW default_transaction_read_only; 在新工作階段中傳回 off 時,寫入操作便會恢復。 在每個資料庫中,以下查詢會列出您那些沒有統計資料的資料表和實體化檢視。 針對清單中的每個關係,執行 ANALYZE <table_name>; 指令。 如果您的使用者沒有分析該關係的權限,請以關係擁有者的身分執行該指令。 分析一個分區表時,也會一併分析其分區。

SELECT c.oid::pg_catalog.regclass AS relation_name
FROM pg_catalog.pg_class AS c
WHERE c.relkind IN ('r', 'm', 'p')
  AND c.reltuples < 0
  AND NOT c.relispartition
  AND c.relpersistence <> 't'
  AND c.relnamespace NOT IN ('pg_catalog'::pg_catalog.regnamespace,
                             'information_schema'::pg_catalog.regnamespace)
  AND NOT EXISTS (SELECT 1
                  FROM pg_catalog.pg_depend AS e
                  WHERE e.classid = 'pg_catalog.pg_class'::pg_catalog.regclass
                    AND e.objid = c.oid
                    AND e.deptype = 'e');

在 PostgreSQL 17 及後續版本中,執行 ANALYZE 可能會失敗,並顯示類似「 function ... does not exist 」的錯誤訊息。 既然如此,請修正「自我檢查查詢 17」中列出的函式,並再次執行 ANALYZE 。 若整個資料庫範圍的 ANALYZE 因發生錯誤而中止,則不會分析剩餘的資料表。 在執行 PostgreSQL 18 時,請一併分析所有包含統計物件的資料表(可透過 psql 指令 \dX`` 列出),以及所有包含 PostGIS 欄位的資料表,因為升級過程不會轉移這些統計資料。

當任務顯示為「已完成」後:

  1. 請確認控制台或 API 中該部署的版本是否顯示為目標版本,且 SHOW server_version; 是否會傳回該版本。 執行 自檢查詢 1,並確認每個高可用性 (HA) 成員皆正在進行資料串流。 同時請確認所有資料庫的寫入功能均已恢復:以下查詢不會返回任何資料列。 若缺少 HA 成員、仍存在名為「pg_basebackup」的資料列,或查詢結果中列出了資料庫,請聯絡技術支援。

    SELECT d.datname AS database_name, s.setconfig
    FROM pg_catalog.pg_db_role_setting AS s
    JOIN pg_catalog.pg_database AS d ON d.oid = s.setdatabase
    WHERE s.setrole = 0
      AND d.datallowconn
      AND NOT d.datistemplate
      AND EXISTS (SELECT 1
                  FROM pg_catalog.unnest(s.setconfig) AS c(setting)
                  WHERE c.setting LIKE 'default_transaction_read_only=%');
    
  2. 更新擴充功能。 此次升級會將每個擴充功能保留在其已安裝的版本。 在每個資料庫中,列出已有更新版本的擴充套件,並分別更新每個擴充套件:

    SELECT name, installed_version, default_version
    FROM pg_catalog.pg_available_extensions
    WHERE installed_version <> default_version;
    
    ALTER EXTENSION <extension_name> UPDATE;
    

    若您是從 PostgreSQL 14、15 或 16 升級至 PostgreSQL 17 或更新版本,更新 pg_stat_statements 時,其 blk_read_time 和 blk_write_time 欄位將分別重新命名為 shared_blk_read_time 和 shared_blk_write_time。 請更新讀取這些欄位的查詢。

  3. 請依照「準備工作」中的說明,恢復延伸部分與遮罩。 從您匯出的內容中重新載入 UNLOGGED 資料表。 將每個 UNLOGGED 序列的數值設定為高於當前使用的數值,例如使用 SELECT setval('<sequence_name>', (SELECT max(<column_name>) FROM <table_name>));``。 請重新建立您先前移除的邏輯複製槽、訂閱及唯讀副本,並啟用您先前停用的訂閱。 在恢復執行依賴的應用程式之前,請先重新連線至使用者,並重新同步資料。

  4. 若您已為某個資料庫設定了 default_transaction_read_only ,請重新設定一次。 此升級會在每個資料庫上重設此設定,因此這些資料庫將重新接受寫入操作。

  5. 請確認 升級後的備份 已完成。 它會複製整個資料庫,因此可能需要數小時。 若您需要針對升級後所做的變更進行特定時間點還原,請在此之前暫停應用程式的寫入操作。

  6. 若您是從 PostgreSQL 14或15升級至 PostgreSQL 16或更新版本,請執行《 版本升級期間的角色權限問題 》一文中所述的角色查詢。 在恢復執行管理角色的工作之前,請先授予所列出的角色權限。

  7. 若由 Terraform 管理部署,而您是在 Terraform 之外進行升級,請依照 《透過 Terraform 升級 》中的說明,將 version 設定為新版本,或直接移除此設定。

  8. 恢復您已暫停的應用程式寫入作業及排程工作。 將您為升級而變更的設定還原,例如 synchronous_commit。

  9. 請重新建置依賴 Unicode 資料的物件,因為較新的 PostgreSQL 版本會使用較新的 Unicode 資料:

    • 除非您是從 PostgreSQL 16升級至 PostgreSQL 17,否則請檢查索引、實體化檢視、檢查約束,以及其表達式中使用 normalize() 或 is_normalized() 的分區鍵。 僅包含在較新 Unicode 版本中新增字元的文字會受到影響。
    • 若您是從 PostgreSQL 17升級至 PostgreSQL 18,請一併檢查使用 unicode_assigned() 的物件。 另請檢查那些在內建的 C.UTF-8 語言環境中,對文字套用正規表達式( ILIKE、lower()、upper() 或 initcap() )的物件。 pg_c_utf8 排序規則,以及在 C.UTF-8 中使用 builtin 地區設定提供者的資料庫,均採用此地區設定。
    • 若您已升級至 PostgreSQL 18,且某個資料庫使用 icu 或 builtin 作為地區設定提供者,請重建該資料庫的全文字搜尋索引及 pg_trgm 索引。

    針對每個受影響的索引,執行 REINDEX INDEX <index_name>; ;針對每個受影響的實體化檢視,執行 REFRESH MATERIALIZED VIEW <view_name>; 。 請確保這些資料列仍符合受影響的檢查約束,且位於正確的分區中。

  10. 將應用程式的運作行為與效能,與您的預備環境測試結果進行比較。

疑難排解

如果服務拒絕了該請求,錯誤訊息會立即顯示。 使用者介面通常會顯示「升級失敗」並附上原因,API 會傳回錯誤訊息,而命令列介面 (CLI) 則會輸出錯誤訊息並附上提示。 請修正該請求,然後重新提交。

如果任務顯示為「已過期」,則表示升級尚未開始,且部署狀態維持不變。 請在沒有其他作業正在執行或排入佇列時,再次提交升級請求,或設定較晚的開始過期時間。

日後顯示為 「失敗」 的任務並未標示出失敗的檢查項目或步驟,且使用者介面亦未顯示失敗原因。 視失敗的步驟而定,部署可能處於以下任一狀態:

  • 關於原始版本:此部署會執行原始版本,並允許寫入操作。 預檢查失敗會導致部署處於此狀態,而在唯讀模式下,服務會在大多數失敗發生後恢復寫入權限。 一次失敗的嘗試仍可能產生長遠的影響。 它可能會移除 old_snapshot、清空 UNLOGGED 中的資料表、重置 UNLOGGED 中的序列,並在 PITR 覆蓋範圍中留下缺口。 它還能重設資料庫層級的「default_transaction_read_only」設定,使這些資料庫重新接受寫入操作。 若您將任何資料庫的 default_transaction_read_only 設定為 on ,則即使僅是預檢查失敗,任何失敗的嘗試也會終止所有客戶端會話。
  • 關於目標版本:部署會執行目標版本,但升級程序在支援團隊完成前仍屬未完成狀態。 主控台和 API 仍可顯示原始碼版本。 在此之前,HA 成員可能無法運行,且備份與交易日誌歸檔可能會失敗。 若自我檢查查詢 1 或 5 顯示有問題,請暫停應用程式寫入作業,直到技術支援完成升級為止。
  • 受損:在技術支援人員恢復該部署之前,該部署將維持唯讀狀態或無法使用,或將在缺少其高可用性 (HA) 成員的情況下繼續運行。 若在轉換或重新啟動階段發生失敗,即使寫入作業已恢復,高可用性 (HA) 成員仍可能處於停止狀態,直到技術支援人員重新啟動它們為止。

要識別該狀態,請以 admin 身分登入,並執行 SHOW server_version;。 在您使用的每個資料庫中,請執行 SHOW default_transaction_read_only;``。 執行 自檢查詢 1,以確認每個高可用性 (HA) 成員皆正在進行資料串流。 如果任務失敗後,admin 無法連線(例如因驗證錯誤所致),請聯絡技術支援。 此次升級不會變更您的登入憑證。

如果部署接受寫入操作、已執行來源版本,且每個高可用性 (HA) 成員皆處於串流狀態,請檢視 預檢查 項目並執行 自我檢查查詢。 請解決所有未滿足的項目,執行按需備份,然後再次提交升級。 在其他所有情況下,或者如果下次嘗試也失敗,請在重新嘗試或進行其他變更之前,先聯絡技術支援。 包括:

  • 部署 CRN 以及發生失敗的任務 ID。 當任務失敗時,請記錄該任務的 ID,因為任務清單僅顯示最近的任務。
  • 原始檔與所需目標檔的 PostgreSQL 版本,以及 SHOW server_version; 的輸出結果。
  • 大致的故障時間及時區。
  • 應用程式是否能夠連線、讀取及寫入。
  • 自我檢查查詢的輸出結果。
  • 每個相關唯讀副本的 CRN,包括任何最近被晉升或刪除的副本。

若請求因內部錯誤而失敗,請聯絡技術支援。 在使用者介面中,此錯誤會顯示「升級失敗」,並附有訊息「無法建立就地升級工作」。 當無法顯示實際原因時,使用者介面也會針對其他遭拒絕的請求顯示此訊息。 若要了解原因,請透過 CLI 或 API 提交請求。 如果該任務的執行時間遠比您在模擬演練中預期的還要長,也請聯絡支援團隊。 發生失敗後,該任務可維持「進行中」狀態(在 CLI 和 API 中顯示為 running ),同時服務會嘗試進行復原。

請僅移除「準備步驟」及「自我檢查問題」清單中所列的物件。 請勿丟棄其他物品以通過檢查。 請改為聯絡客服。

從唯讀抄本升級

從來源部署 建立一個唯讀複本,並等待該複本完成同步。 接著,請使用 /remotes/promotion 端點 來推廣並升級該副本。 將 version 設定為複本在其功能清單中列出的目標:

curl -X POST \
  https://api.{region}.databases.cloud.ibm.com/v5/ibm/deployments/{id}/remotes/promotion \
  -H 'Authorization: Bearer <IAM_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "promotion": {
        "version": "18",
        "skip_initial_backup": false
    }
}'

僅當您希望跳過升級所產生的初始備份時,才將 skip_initial_backup 設定為 true 。 此設定可縮短升級作業的時間,但升級後的部署要恢復正常,則需在後續執行一次成功的排程或隨選備份。

若版本升級的升級操作失敗,該服務將停用已升級的部署。 請與支援中心聯絡。 在正式採用之前,請先於預備部署的複本上,針對版本升級進行升級演練。

透過還原備份進行升級

將備份還原 至使用受支援目標版本的部署。 若您透過 CLI 或 API 還原備份,且未指定資源分配參數,則新部署將採用原始部署在建立備份時所設定的資源分配。 在使用者介面中,還原頁面會以來源部署的當前配額為起點,您可以對此進行變更。

在使用者介面中還原備份

在部署儀表板中的「備份與還原」區塊,點選您要使用的備份旁的 「還原備份」。 在開啟的頁面中,請於「資料庫版本」中選取一個受支援的目標版本,並設定新部署的選項。 接著,請按一下「還原備份」。

透過 CLI 還原備份

請在 -p 的 JSON 參數中指定目標版本和備份 ID 來建立部署:

ibmcloud resource service-instance-create example-upgrade databases-for-postgresql standard us-south \
  -p '{
  "backup_id": "crn:v1:bluemix:public:databases-for-postgresql:us-south:a/54e8ffe85dcedf470db5b5ee6ac4a8d8:1b8f53db-fc2d-4e24-8470-f82b15c71717:backup:06392e97-df90-46d8-98e8-cb67e9e0a8e6",
  "version": "18"
}' \
  --service-endpoints "public"

透過 API 還原備份

使用 Resource 控制器 API, 將備份還原至運行目標版本的新部署環境中。 請指定部署名稱、位置、資源群組、方案、備份 ID 以及目標版本:

curl -X POST \
  https://resource-controller.cloud.ibm.com/v2/resource_instances \
  -H 'Authorization: Bearer <IAM_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my-instance",
    "target": "bluemix-us-south",
    "resource_group": "5g9f447903254bb58972a2f3f5a4c711",
    "resource_plan_id": "databases-for-postgresql-standard",
    "parameters": {
      "backup_id": "crn:v1:bluemix:public:databases-for-postgresql:us-south:a/54e8ffe85dcedf470db5b5ee6ac4a8d8:1b8f53db-fc2d-4e24-8470-f82b15c71717:backup:06392e97-df90-46d8-98e8-cb67e9e0a8e6",
      "version": "18"
    }
  }'

強制升級

在停用日期之後,所有運行已廢棄版本且處於活躍狀態的 Databases for PostgreSQL 部署,都將自動升級至下一個受支援的版本。

強制升級屬於 IPMVU,因此請在產品生命週期結束日期之前完成 IPMVU 的製備。

在生命終止日期之前升級以避免以下風險:

  • 沒有為此類強制升級提供 SLA。
  • 您可能會遇到部分資料遺失的情況。
  • 您的應用程式可能會出現長時間的停機狀況。
  • 如果您的應用程式與新版本不相容,可能會停止運作。
  • 您無法控制您的部署進行此升級的時間。
  • 此強制升級沒有回滾過程。
  • 如果由 Terraform 管理部署並設定了 version,那麼在強制升級後,所有 ` `terraform plan` ` 請求都會失敗,直到您更新 ` `version 為止。

有關產品生命週期結束日期,請參閱 版本政策頁面。

版本升級過程中的角色權限問題

在 PostgreSQL 16 及後續版本中,具有「CREATEROLE」屬性的角色(例如 admin ),需要另一個角色具備「ADMIN OPTION」才能進行管理。 管理角色包括變更其密碼或屬性、刪除該角色,以及授予其成員資格。 從 PostgreSQL 14 或 15 升級至 16 或更高版本後,admin 不會針對升級前已存在的角色提供此選項。 因此,那些以「admin」身分管理這些角色的工作(例如密碼輪替),將會失敗。 如需更多資訊,請參閱《 PostgreSQL 16》發行說明、角色屬性及 角色授權。

例如,變更密碼時會出現以下錯誤:

ERROR:  permission denied to alter role
DETAIL:  To change another role's password, the current user must have the CREATEROLE attribute and the ADMIN option on the role.

在升級之前,請以 admin 的身分執行以下查詢。 此處列出了升級後 admin 無法管理的角色,但您透過使用者介面 (UI)、命令列介面 (CLI) 或 API 所建立的使用者除外。 在 PostgreSQL 16 及後續版本中,admin 同樣無法變更這些使用者,因此請透過使用者介面 (UI)、命令列介面 (CLI) 或 API 來管理他們。

SELECT r.rolname AS role_name,
       pg_catalog.pg_has_role(r.oid, 'admin'::name, 'MEMBER') AS member_of_admin
FROM pg_catalog.pg_roles AS r
WHERE NOT r.rolsuper
  AND NOT r.rolreplication
  AND r.rolname <> 'admin'
  AND r.rolname !~ '^(pg_|ibm-)'
  AND NOT EXISTS (
      SELECT 1
      FROM pg_catalog.pg_auth_members AS m
      JOIN pg_catalog.pg_roles AS b ON b.oid = m.roleid
      WHERE m.member = r.oid
        AND b.rolname IN ('ibm-cloud-base-user', 'ibm-cloud-base-user-ro'))
  AND NOT pg_catalog.pg_has_role(r.oid, 'MEMBER WITH ADMIN OPTION')
ORDER BY 1;

若要繼續管理已列出的角色,請在升級前將該角色授予 admin:

GRANT <role_name> TO admin WITH ADMIN OPTION;

此授權請求因某個角色的「member_of_admin」值為「t」而失敗,因為該角色是「admin」的成員。 升級後,admin 無法管理此類角色。

升級至 PostgreSQL 16 或更高版本後,請再次執行該查詢。 對於每個 member_of_admin 值為 f`` 的列出角色,請在連線至 ibmclouddb 或任何非 postgres 的資料庫時,執行以下輔助程式。 請勿包含其他角色,因為只要有一項補助申請未獲核准,整項徵件即告作廢。 您可以安全地多次執行此輔助程式:

SELECT grant_admin_option_to_roles('role1', 'role2', 'role3');

這兩項授權也使 admin 成為該角色的成員,因此 admin 可以使用該角色的權限。

主要 PostgreSQL 版本的變更日誌