就地升級資料庫主要版本

MySQL   |  PostgreSQL   |  SQL Server

本頁面說明如何就地升級 Cloud SQL 執行個體，而非遷移資料，藉此升級資料庫主要版本。

簡介

資料庫軟體供應商會定期發布新的主要版本，其中包含新功能、效能改善和安全性強化。Cloud SQL 會在新版本發布後採用。Cloud SQL 支援新的主要版本後，您可以升級執行個體，讓資料庫保持最新狀態。

您可以就地升級執行個體的資料庫版本，或遷移資料。就地升級是升級執行個體主要版本的簡便方法。您不必遷移資料或變更應用程式連線字串。就地升級可讓您在升級後，保留目前執行個體的名稱、IP 位址和其他設定。就地升級不需要移動資料檔案，而且可以更快完成。在某些情況下，停機時間會比遷移資料所需的時間短。

PostgreSQL 適用的 Cloud SQL 就地升級作業會使用 pg_upgrade 公用程式。

規劃主要版本升級

1. 確認您具備執行主要版本升級所需的角色：Cloud SQL 擁有者或 Cloud SQL 管理員。

2. 選擇目標主要版本。

   gcloud

   如要瞭解如何安裝及開始使用 gcloud CLI，請參閱「安裝 gcloud CLI」。如要瞭解如何啟動 Cloud Shell，請參閱「使用 Cloud Shell」。

   如要查看執行個體可就地升級的資料庫版本，請按照下列步驟操作：

   1. 執行下列指令。

   gcloud sql instances describe INSTANCE_NAME
      

   將 INSTANCE_NAME 替換為執行個體名稱。

   2. 在指令輸出內容中，找出標示為 upgradableDatabaseVersions 的部分。
   3. 每個子節都會傳回可升級的資料庫版本。在每個子節中，查看下列欄位。
   • majorVersion：可就地升級的主要版本。
   • name：包含主要版本的資料庫版本字串。
   • displayName：資料庫版本的顯示名稱。
   注意：如果輸出內容中未顯示 upgradableDatabaseVersions，表示執行個體可能已執行最新支援的主要資料庫版本，或執行個體未執行。外部副本無法就地升級。

   REST v1

   如要查看哪些目標資料庫版本可用於主要版本就地升級，請使用 Cloud SQL Admin API 的 instances.get 方法。

   使用任何要求資料之前，請先修改下列項目的值：

   • INSTANCE_NAME：執行個體名稱。

   HTTP 方法和網址：

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

   請展開以下其中一個選項，以傳送要求：

   curl (Linux、macOS 或 Cloud Shell)

   注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

   執行下列指令：

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME"

   PowerShell (Windows)

   注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

   執行下列指令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

   您應該會收到如下的 JSON 回覆：

   
   upgradableDatabaseVersions:
   
   {
     major_version: "POSTGRES_15_0"
     name: "POSTGRES_15_0"
     display_name: "PostgreSQL 15.0"
   }
   
   

   注意：如果回應中未顯示 upgradableDatabaseVersions，表示執行個體可能已執行支援的最新主要資料庫版本，或執行個體未執行。外部副本無法就地升級。

   REST v1beta4

   如要查看執行個體的主要版本就地升級有哪些可用的目標資料庫版本，請使用 Cloud SQL Admin API 的 instances.get 方法。

   使用任何要求資料之前，請先修改下列項目的值：

   • INSTANCE_NAME：執行個體名稱。

   HTTP 方法和網址：

   GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

   請展開以下其中一個選項，以傳送要求：

   curl (Linux、macOS 或 Cloud Shell)

   注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

   執行下列指令：

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME"

   PowerShell (Windows)

   注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

   執行下列指令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

   您應該會收到如下的 JSON 回覆：

   
   upgradableDatabaseVersions:
   
   {
     major_version: "POSTGRES_15_0"
     name: "POSTGRES_15_0"
     display_name: "PostgreSQL 15.0"
   }
   
   

   注意：如果回應中未顯示 upgradableDatabaseVersions，表示執行個體可能已執行支援的最新主要資料庫版本，或執行個體未執行。外部副本無法就地升級。

   如需 Cloud SQL 支援的資料庫版本完整清單，請參閱「資料庫版本和版本政策」。

3. 請考量各資料庫主要版本提供的功能，並解決不相容問題。

   • PostgreSQL 18
   • PostgreSQL 17
   • PostgreSQL 16
   • PostgreSQL 15
   • PostgreSQL 14
   • PostgreSQL 13
   • PostgreSQL 12
   • PostgreSQL 11
   • PostgreSQL 10

   新的主要版本會導入不相容的變更，您可能需要修改應用程式程式碼、結構定義或資料庫設定。升級資料庫執行個體前，請先查看目標主要版本的版本資訊，判斷必須解決的不相容問題。

4. 執行升級預先檢查。

5. 透過模擬測試來測試升級作業。

   在升級正式資料庫之前，請先在測試環境中模擬測試端對端升級程序。您可以複製執行個體，建立完全相同的資料副本，用來測試升級程序。

   除了驗證升級是否成功完成，也請執行測試，確保應用程式在升級後的資料庫中運作正常。

   注意： 執行主要版本升級前，請確認磁碟空間足夠。如果您尚未啟用自動增加儲存空間，請記下升級模擬測試執行個體使用的磁碟儲存空間。這有助於判斷是否需要在升級前，增加正式環境執行個體的儲存空間容量。

6. 決定升級時間。

   升級期間，執行個體會暫時無法使用。請安排在資料庫活動較少的時段升級。建議您不要在流量偏高或資料庫執行長時間交易時，升級主要版本。

準備升級主要版本

升級前，請先完成下列步驟。

1. 檢查 template 和 postgres 資料庫的 LC_COLLATE 值。每個資料庫的字元集都必須是 en_US.UTF8。

   如果 template 和 postgres 資料庫的 LC_COLLATE 值不是 en_US.UTF8，主要版本升級作業就會失敗。如要修正這個問題，請在執行升級前，將 LC_COLLATE 值變更為 en_US.UTF8 (如果任一資料庫的字元集不是 en_US.UTF8)。

   如要變更資料庫的編碼，請按照下列步驟操作：

   1. 傾印資料庫。
   2. 捨棄資料庫。
   3. 建立採用不同編碼的新資料庫 (在本例中為 en_US.UTF8)。
   4. 重新載入資料。

   另一個選項是重新命名資料庫：

   1. 關閉與資料庫的所有連線。
   2. 重新命名資料庫。
   3. 更新應用程式設定，改用新的資料庫名稱。
   4. 使用預設編碼建立新的空白資料庫。

   建議您先在複製的執行個體上執行這些步驟，再套用至正式環境執行個體。

2. 管理其餘 PostgreSQL 擴充功能。

   大多數擴充功能都適用於升級後的資料庫主要版本。捨棄目標版本不再支援的任何擴充功能。舉例來說，如果您要升級至 PostgreSQL 11 以上版本，請捨棄 chkpass 擴充功能。

   您可以手動將 PostGIS 及其相關擴充功能升級至最新支援版本。

   有時從 PostGIS 2.x 版升級，可能會導致資料庫物件殘留，且與 PostGIS 擴充功能無關。這可能會導致升級作業無法進行。如要瞭解如何解決這個問題，請參閱「修正損壞的 postgis 光柵安裝」。

   有時，由於物件使用已淘汰的函式，因此無法升級至 PostGIS 3.1.7 以上版本。這可能會導致升級作業無法執行。如要查看升級狀態，請執行 SELECT PostGIS_full_version();。如果出現警告，請捨棄使用已淘汰函式的任何物件，並將 PostGIS 擴充功能更新至任何中繼或更高版本。完成這些動作後，請再次執行 SELECT PostGIS_full_version(); 指令。確認沒有出現任何警告。然後繼續執行升級作業。

   如要進一步瞭解如何升級 PostGIS 擴充功能，請參閱「升級 PostGIS」。如要瞭解升級 PostGIS 的相關問題，請參閱「檢查 PostgreSQL 執行個體的版本」。
3. 管理自訂資料庫旗標。檢查您為 PostgreSQL 執行個體設定的任何自訂資料庫旗標名稱。如要瞭解與這些旗標相關的問題，請參閱「檢查 PostgreSQL 執行個體的自訂旗標」。
4. 從一個主要版本升級至另一個版本時，請嘗試連線至各個資料庫，確認是否有任何相容性問題。確認資料庫可以互相連線。請檢查每個資料庫的 datallowconn 欄位，確保允許連線。t 值表示允許，f 值則表示無法建立連線。
5. 如果您使用 Datadog 安裝作業將 Cloud SQL 執行個體升級至 PostgreSQL 10 以上版本，請先捨棄 pg_stat_activity() 函式，再執行升級。

6. 管理含有大量物件的執行個體。

   就地主要版本升級所需的時間，取決於執行個體中的資料庫物件數量。如果執行個體含有大量物件 (尤其是資料表和索引)，升級時間可能會大幅增加。這會增加作業逾時的風險。Cloud SQL 經過最佳化調整，適用於關係數量不超過 100,000 個的執行個體。如果執行個體超過這個值，升級作業不會遭到封鎖，但會被視為較不可靠，且更有可能需要較長時間，或在 6 小時逾時後失敗。

   如果執行個體包含大量物件，請先執行下列操作，再開始主要升級程序：

   1. 稽核並捨棄未使用的物件：找出並移除所有空白資料表、僅用於測試的資料表，或任何其他不再需要的資料庫物件 (結構定義、檢視表、函式)。
   2. 最佳化表格結構：
      • 如果您使用資料表分區，過多的分區可能會導致關係數量偏高。在這種情況下，請評估如何減少使用的分區數量。
      • 建議您將歷來資料或不常存取的資料，遷移至其他資料儲存庫選項。這可能會減少有效資料表的數量，或縮減現有資料表的大小和複雜度。
   3. 執行升級測試：在正式版執行個體的本機副本上，模擬執行升級作業。這樣一來，您就能實際估算所需時間，並找出任何潛在問題。如果資料庫含有大量物件，這項預估值就特別重要。

   減少整體物件數量和複雜度，可降低主要版本升級的風險和停機時間。

7. 管理含有大型物件 (LOB) 的執行個體。

   就地升級程序會使用 PostgreSQL pg_upgrade 公用程式。如果資料庫含有大量 LOB，這項程序可能會耗費許多時間，甚至可能因逾時而導致升級失敗。

   如要查看資料庫中的大型物件數量，請使用 PostgreSQL 用戶端 (例如 psql) 連線至資料庫執行個體，然後執行下列查詢：

       SELECT count(*) AS total_large_objects FROM pg_largeobject_metadata;
     

   如果執行個體包含超過 3, 000 萬個 LOB，逾時風險就會增加。在這種情況下，請考慮在開始升級前採取下列行動：

   1. 清除孤立的大型物件：PostgreSQL 不會自動移除不再參照的 LOB。使用 contrib 模組中的 vacuumlo 公用程式，移除孤立的 LOB。您必須從可連線至 Cloud SQL 執行個體的用戶端機器執行這項指令。
      • 如果沒有 vacuumlo，請在用戶端機器上安裝 postgresql-contrib 套件。
      • 執行下列指令進行模擬測試，查看哪些 LOB 會遭到刪除：

                vacuumlo -h INSTANCE_IP -U DATABASE_USER --dry-run DATABASE_NAME
                  

        將 INSTANCE_IP、DATABASE_USER 和 DATABASE_NAME 替換為您的執行個體詳細資料。系統會提示您輸入使用者密碼。
      • 執行下列指令，移除識別出的 LOB：

                vacuumlo -h INSTANCE_IP -U DATABASE_USER DATABASE_NAME
                  

        執行 vacuumlo 後，請重新檢查 LOB 數量，確認清除作業是否成功。
   2. 手動刪除大型物件：檢查應用程式的資料保留政策，並移除不再需要的 LOB。
   3. 增加執行個體資源：暫時或永久增加執行個體的 vCPU 和記憶體。這可為 pg_upgrade 程序提供更多資源。
   4. 遷移資料：如果 LOB 數量無法充分減少，請考慮遷移資料來升級。您可以使用 pg_dump 和 pg_restore，為 LOB 建立自訂方法。標準邏輯複製方法可能不完全支援 LOB，因此可能需要額外步驟和停機時間，才能遷移 LOB。
8. 警告：PostgreSQL 的就地主要版本升級程序會刪除執行個體上所有現有的邏輯複製運算單元。如果升級完成後未重新建立這些運算單元，複製串流就會中斷。

   記錄您需要用來重新建立執行個體上所有邏輯複製槽的資訊，包括 pglogical、PostgreSQL 內建邏輯複製、Datastream 或任何其他邏輯解碼消費者使用的槽。

已知限制

下列限制會影響 PostgreSQL 適用的 Cloud SQL 就地主要版本升級：

• 您無法對外部副本執行就地主要版本升級。
• 如果執行個體有超過 1,000 個資料庫，升級版本可能需要較長時間，甚至會逾時。
• 使用 select * from pg_largeobject_metadata; 陳述式，查詢 Cloud SQL 執行個體中每個 PostgreSQL 資料庫的大型物件數量。如果所有資料庫的結果超過 1, 000 萬個大型物件，升級就會失敗。Cloud SQL 會復原至資料庫的先前版本。
• 在就地升級至 PostgreSQL 16 以上主要版本前，請先將所有資料庫的 PostGIS 擴充功能升級至 3.4.0 版。PostgreSQL 18 則應升級至 PostGIS 3.6.0 版。
• 就地升級至 PostgreSQL 17 主要版本前，請先將所有資料庫的 rdkit 擴充功能升級至 4.6.1 版。
• 就地升級至 PostgreSQL 16、17 或 18 前，請先將所有資料庫的 pg_squeeze 擴充功能分別升級至 1.6、1.7 或 1.8 版。
• 如果您使用的是 PostgreSQL 9.6、10、11 或 12 版，則不支援 PostGIS 擴充功能 3.4.0 版。因此，如要就地執行 PostgreSQL 16 以上版本的「主要版本」升級，必須先升級至 PostgreSQL 中繼版本 (13、14 或 15 版)。

• 如果為執行個體安裝 pg_ivm 擴充功能，就無法執行主要版本升級。如要修正這個問題，請解除安裝這項擴充功能，然後執行升級。如要進一步瞭解擴充功能，請參閱「設定 PostgreSQL 擴充功能」。

• 如果啟用 vacuum_defer_cleanup_age 和 force_parallel_mode 旗標，就無法執行主要版本升級。如要修正這個問題，請刪除這些旗標，然後執行升級作業。如要進一步瞭解旗標 (包括如何刪除)，請參閱「設定資料庫旗標」。

  注意： PostgreSQL 16 以上版本已淘汰 vacuum_defer_cleanup_age 旗標，並將 force_parallel_mode 旗標重新命名為 debug_parallel_query。

評估執行個體的升級準備度

Cloud SQL 可讓您在主要版本升級前，對執行個體執行預檢。這項預先檢查是長時間執行的作業 (LRO)，會檢查執行個體是否可以升級。這項功能有助於在升級前找出潛在問題，例如不相容、設定問題或資料問題。

預先檢查會確認執行個體是否可以升級，或列出您需要先修正的問題和解決方案。這些問題可能是由不相容的擴充功能、不支援的依附元件或資料格式問題所造成。

Cloud SQL 可與工作負載平行執行預先檢查程序。在執行主要版本升級前執行預檢，有助於避免升級失敗。

執行預先檢查時，會發生下列其中一種情況：

• 未發現任何問題：預先檢查已順利完成，未發現任何問題。
• 發現問題：預先檢查已順利完成，但發現會阻礙升級的錯誤。請務必先解決問題，再升級。
• 發現警告：預先檢查順利完成，但發現警告。查看警告。 建議您先解決所有問題，再繼續升級。

視預先檢查結果而定，您可以繼續升級，或先修正發現的問題再升級。

限制

使用主要版本升級預先檢查時，請注意下列限制：

• 執行個體狀態必須設為 RUNNING。

• 執行個體必須是主要執行個體，預先檢查不支援副本執行個體。

• 執行個體不得有任何待處理的封鎖作業。如果有待處理的封鎖作業，預先檢查會失敗，並顯示下列訊息：

  Operation failed because another operation was already in progress. Try
  your request after the current operation is complete.
  

• 預先檢查作業必須連線至執行個體上的所有資料庫。如果資料庫無法存取、鎖定或沒有回應，預先檢查可能會失敗或顯示錯誤。建議在資料庫負載較低時執行預先檢查。

事前準備

• 確認執行個體已啟用 Cloud SQL Admin API。
• 確認您具備 cloudsql.instances.preCheckMajorVersionUpgrade IAM 權限。

執行預先檢查

如要執行主要版本升級預先檢查，請按照下列步驟操作：

控制台

1. 前往 Google Cloud 控制台的「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面。

   前往「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面

2. 找出要執行預先檢查的執行個體。 點選執行個體名稱，開啟執行個體的「Overview」(總覽) 頁面。
3. 按一下 [編輯]。
4. 在「執行個體資訊」中，按一下「驗證升級」。
5. 在「Validate upgrade」(驗證升級作業) 對話方塊中，選取要升級至哪個資料庫版本，然後按一下「Validate」(驗證)。

   預先檢查作業隨即開始。在「Operations」(作業) 通知導覽匣中，監控預先檢查作業的狀態。

6. 預先檢查作業完成後，系統會開啟名為「Validate upgrade results」(驗證升級結果) 的新視窗。這個視窗會顯示預先檢查程序的結果。結果可能是下列其中一項：
   • 如果預先檢查作業未發生錯誤，請按一下「Upgrade page」(升級頁面)，開始升級程序。
   • 如果預先檢查作業包含 info 訊息，請查看發現項目。準備好升級時，請按一下「升級頁面」，開始升級程序。
   • 如果預先檢查包含 warning 訊息，請查看結果。建議您先解決這些警告，再繼續升級，但這些訊息不會阻礙升級程序。
   • 如果預先檢查作業包含 errors，請查看發現項目。請解決錯誤，然後重新執行預先檢查程序。您必須先解決所有錯誤，才能開始升級程序。

gcloud

1. 使用 gcloud sql instances pre-check-major-version-upgrade 執行預先檢查：

   gcloud  sql instances pre-check-major-version-upgrade INSTANCE_NAME \
     --target-database-version=TARGET_DATABASE_VERSION \
     --project=PROJECT_ID \
     [--async]
      

   更改下列內容：

   • INSTANCE_NAME：執行個體的名稱。
   • TARGET_DATABASE_VERSION：要將執行個體升級至的主要版本。如要查看資料庫版本，請參閱「規劃升級」。
   • PROJECT_ID： Google Cloud 專案的 ID。

   選用：使用 --async 旗標，以非同步方式執行指令。

2. 如果您使用 --async 旗標以非同步方式執行 pre-check-major-version-upgrade 指令，請執行下列操作：

   1. 取得預先檢查作業名稱：

      使用 gcloud sql operations list 指令，並加上 --instance 旗標：

      gcloud sql operations list --instance=INSTANCE_NAME

      更改下列內容：

      • INSTANCE_NAME：執行個體的名稱。

   2. 監控預先檢查狀態。

      使用 gcloud sql operations describe 指令：

      gcloud sql operations describe OPERATION_NAME

      更改下列內容：

      • OPERATION_NAME：在上一個步驟中擷取的預先檢查作業名稱。
3. 如果您未以非同步方式執行 pre-check-major-version-upgrade 指令，請等待預先檢查完成，再查看結果。

REST v1

1. 執行預先檢查。

   使用任何要求資料之前，請先修改下列項目的值：

   • PROJECT_ID：專案 ID
   • INSTANCE_ID：執行個體 ID
   • TARGET_DATABASE_VERSION：要升級至的主要版本。如要查看可用資料庫版本清單，請參閱「規劃升級」。

   HTTP 方法和網址：

   POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade

   JSON 要求主體：

   {
     "preCheckMajorVersionUpgradeContext": {
       "targetDatabaseVersion": "TARGET_DATABASE_VERSION"
     }
   }
   

   請展開以下其中一個選項，以傳送要求：

   curl (Linux、macOS 或 Cloud Shell)

   注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade"

   PowerShell (Windows)

   注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade" | Select-Object -Expand Content

   您應該會收到如下的 JSON 回覆：

   {
     "message": "Precheck description of finding",
     "message_type": "ERROR",
     "actions_required": [
       "Precheck action required to fix the finding"
     ]
   }
   

2. 取得預先檢查作業名稱。

   請使用 GET 要求和 operations.list 方法，並將 PROJECT_ID 替換為專案 ID。

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

   更改下列內容：

   • PROJECT_ID： Google Cloud 專案的 ID。

3. 監控預先檢查狀態。

   使用 GET 要求和 operations.list 方法：

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

   更改下列內容：

   • PROJECT_ID： Google Cloud 專案的 ID。
   • OPERATION_NAME：在上一個步驟中擷取的預先檢查作業名稱。

REST v1beta4

1. 執行預先檢查。

   使用任何要求資料之前，請先修改下列項目的值：

   • PROJECT_ID：專案 ID
   • INSTANCE_ID：執行個體 ID
   • TARGET_DATABASE_VERSION：要升級至的主要版本。如要查看可用的資料庫版本清單，請參閱「規劃升級」。

   HTTP 方法和網址：

   POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade

   JSON 要求主體：

   {
     "preCheckMajorVersionUpgradeContext": {
       "targetDatabaseVersion": "TARGET_DATABASE_VERSION"
     }
   }
   

   請展開以下其中一個選項，以傳送要求：

   curl (Linux、macOS 或 Cloud Shell)

   注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade"

   PowerShell (Windows)

   注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

   將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade" | Select-Object -Expand Content

   您應該會收到如下的 JSON 回覆：

   {
     "message": "Precheck description of finding",
     "message_type": "ERROR",
     "actions_required": [
       "Precheck action required to fix the finding"
     ]
   }
   

2. 取得預先檢查作業名稱。

   請使用 GET 要求和 operations.list 方法，並將 PROJECT_ID 替換為專案 ID。

   GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations

   更改下列內容：

   • PROJECT_ID： Google Cloud 專案的 ID。

3. 監控預先檢查狀態。

   使用 GET 要求和 operations.list 方法：

   GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operation/OPERATION_NAME

   更改下列內容：

   • PROJECT_ID： Google Cloud 專案的 ID。
   • operation_name：在上一個步驟中擷取的預先檢查作業名稱。

查看預先檢查結果

預先檢查完成後，執行個體會準備好升級，或是有問題需要處理。

可開始升級

如果預先檢查順利完成，且 preCheckResponse 陣列為空白，表示未發現任何問題或警告。執行個體已可升級主要版本。如要繼續，請參閱「執行主要版本升級」。

尚未準備好升級

如果預先檢查成功執行，且 preCheckResponse 陣列包含問題，表示執行個體尚未準備好升級，需要處理。系統找出的問題不一定會阻礙升級。這些問題會記錄在 preCheckResponse 中，並顯示下列訊息類型：

類型	說明	封鎖升級？
INFO	資訊訊息。	否
WARNING	系統發現潛在問題，但不會阻礙升級。 Cloud SQL 建議您先查看並解決警告，再升級，確保完全相容。	否
ERROR	發現會阻礙升級的重大問題。這些問題可能會導致升級失敗。您必須先解決這些問題，才能升級執行個體。	是

如果執行個體只有 INFO 或 WARNING 訊息，可以升級，但升級後可能會發生問題。建議您先查看訊息詳細資料並解決問題，再升級。如果執行個體有 ERROR 訊息，您必須先解決這些問題，才能升級。

每種問題類型都包含 message 和 actions_required 欄位。請查看各項問題，瞭解問題類型和解決方法。如要進一步瞭解常見問題和解決方案，請參閱「常見的主要版本升級預先檢查錯誤」。

解決問題後，請重新執行預先檢查，確認執行個體已準備好升級。預先檢查完成後，即可升級執行個體。

執行主要版本升級

您可以升級單一 Cloud SQL 執行個體的主要版本，也可以升級主要執行個體的主要版本，並將所有副本納入升級範圍，包括串聯副本和跨區域副本。

升級單一執行個體的主要版本

當您為單一執行個體啟動升級作業時，Cloud SQL 會執行下列操作：

1. 檢查執行個體的設定，確保執行個體與升級作業相容。
2. Cloud SQL 驗證設定後，會將執行個體設為無法使用。
3. 建立升級前備份。
4. 對執行個體執行升級作業。
5. 讓執行個體可供使用。
6. 建立升級後備份。

注意： 如果您使用唯讀副本，並選擇不將副本納入主要版本升級作業，則必須先升級唯讀副本，再升級主要執行個體。升級副本後，就無法復原副本的資料庫版本。升級主要執行個體後，才能使用升級後副本的複製資料庫。

控制台

1. 前往 Google Cloud 控制台的「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面。

   前往「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面

2. 點選執行個體名稱，開啟執行個體的「總覽」頁面。
3. 按一下 [編輯]。
4. 在「Instance info」(執行個體資訊) 區段中，按一下「Upgrade」(升級) 按鈕，並確認要前往升級頁面。
5. 在「Choose a database version」(選擇資料庫版本) 頁面中，按一下「Database version for upgrade」(要升級的資料庫版本) 清單，然後選取其中一個可用的資料庫主要版本。
6. 按一下「繼續」。
7. 在「Instance ID」(執行個體 ID) 方塊中輸入執行個體名稱，然後按一下「Start upgrade」(開始升級) 按鈕。

這項作業需要幾分鐘才能完成。

在執行個體的「Overview」(總覽) 頁面中，確認執行個體名稱下方顯示升級後的資料庫主要版本。

gcloud

1. 開始升級。

   使用 gcloud sql instances patch 指令，並加上 --database-version 旗標。

   執行指令前，請先替換下列項目：

   • INSTANCE_NAME：執行個體的名稱。
   • DATABASE_VERSION：資料庫主要版本的列舉，必須晚於目前版本。請指定資料庫版本，做為執行個體可升級的主要版本。您可以在升級計畫的第一個步驟中取得這個列舉。 如需資料庫版本列舉的完整清單，請參閱 SqlDatabaseEnums。

   gcloud sql instances patch INSTANCE_NAME \
   --database-version=DATABASE_VERSION

   主要版本升級作業需要幾分鐘才能完成。您可能會看到一則訊息，指出作業時間比預期長。您可以忽略這則訊息，或執行 gcloud sql operations wait 指令關閉訊息。

2. 取得升級作業名稱。

   使用 gcloud sql operations list 指令，並加上 --instance 旗標。

   執行指令前，請先替換下列項目： * INSTANCE_NAME：執行個體的名稱。

   gcloud sql operations list --instance=INSTANCE_NAME

3. 監控升級狀態。

   使用 gcloud sql operations describe 指令。

   執行指令前，請將 OPERATION 變數替換為上一步驟中擷取的升級作業名稱。

   gcloud sql operations describe OPERATION

REST v1

1. 開始就地升級。

   請使用 instances:patch 方法傳送 PATCH 要求。

   使用任何要求資料之前，請先替換下列變數：

   • PROJECT_ID：專案 ID。
   • INSTANCE_NAME：執行個體的名稱。

   HTTP 方法和網址：

   PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

   JSON 要求主體：

   {
     "databaseVersion": DATABASE_VERSION
   }

   將 DATABASE_VERSION 替換為資料庫主要版本的列舉，該版本必須晚於目前版本。請指定資料庫版本，做為執行個體可升級的主要版本。您可以在升級計畫的第一個步驟中取得這個列舉。 如需資料庫版本列舉的完整清單，請參閱 SqlDatabaseVersion。

2. 取得升級作業名稱。

   請將 PROJECT_ID 替換為專案 ID，然後使用 operations.list 方法傳送 GET 要求。

   HTTP 方法和網址：

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

3. 監控升級狀態。

   請使用 GET 要求和 operations.get 方法，並替換下列變數：

   • PROJECT_ID：專案 ID。
   • OPERATION_NAME：在上一個步驟中擷取的升級作業名稱。

   HTTP 方法和網址：

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

Terraform

如要使用 Terraform 升級資料庫的主要版本，您必須將 google_sql_database_instance 資源定義中的 database_version 引數設為目標主要版本。您必須使用 Google Cloud 4.34.0 以上版本的 Terraform 供應商。

以下範例說明基本的 google_sql_database_instance 設定。如要升級主要版本，請將 database_version 引數設為相關的主要版本。

resource "google_sql_database_instance" "default" {
  name             = "postgres-instance"
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
  }
}

對 Terraform 引數進行下列變更：

• database_version：將此值設為升級的目標主要版本。
• deletion_protection：定義根層級 Terraform 防護措施，防止執行個體遭到刪除。
  • true：防止 Terraform 刪除執行個體。任何預計刪除這項資源的 Terraform 作業都會遭到封鎖。
  • false：允許 Terraform 刪除執行個體。

注意：這與 GCP 層級防刪除功能 (settings.deletion_protection_enabled) 不同。

查看 Terraform 計畫

套用任何變更前，請務必執行 terraform plan 並仔細檢查輸出內容。資源名稱旁的符號代表 Terraform 套用變更的方式：

• ~ 就地更新：這個符號表示 Terraform 會修改現有執行個體。變更 database_version 時，這是就地主要版本升級的預期安全結果。
• +/- 重新建立 (強制替換)：這個符號表示 Terraform 打算刪除目前的執行個體，並建立新的執行個體。
  警告：如果變更 database_version 後，google_sql_database_instance 資源旁顯示 +/-，請勿繼續執行 terraform apply。這項操作會刪除執行個體和所有相關資料。
  • 如果將 deletion_protection 設為 true，Terraform 會顯示錯誤訊息，並禁止這項危險的替換作業。您必須在設定中明確設定 deletion_protection = false，並再次執行 terraform apply 來更新狀態，後續的 apply 才會允許刪除及重新建立。
  • 如果 deletion_protection 設為 false，terraform apply 會繼續執行，並遺失資料。

  如果設定變更，或就地修改的升級路徑不受支援，系統可能會排定更換 (刪除並重新建立) 執行個體。如果發現執行個體已排定刪除並重新建立，請立即停止並調查排定替換的原因，再繼續操作。

查看 terraform plan 輸出內容，確認只會針對資料庫版本變更執行就地更新 (~)，然後套用設定

如要在 Google Cloud 專案中套用 Terraform 設定，請完成下列各節的步驟。

準備 Cloud Shell

1. 啟動 Cloud Shell。

2. 設定要套用 Terraform 設定的預設 Google Cloud 專案。

   每個專案只需執行這個指令一次，而且可以在任何目錄中執行。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 設定檔中設定明確的值，環境變數就會遭到覆寫。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為「根模組」)。

1. 在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱必須有 .tf 副檔名，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您正在進行教學課程，可以複製每個章節或步驟中的程式碼範例。

   將程式碼範例複製到新建立的 main.tf。

   您也可以從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分，建議您採用這種做法。

3. 請查看並修改範例參數，以便套用至您的環境。
4. 儲存變更。
5. 初始化 Terraform。每個目錄只需執行一次這項操作。

   terraform init

   如要使用最新版 Google 供應商，請視需要加入 -upgrade 選項：

   terraform init -upgrade

套用變更

1. 查看設定，確認 Terraform 要建立或更新的資源符合預期：

   terraform plan

   視需要修正設定。

2. 執行下列指令，並在提示中輸入 yes，套用 Terraform 設定：

   terraform apply

   等待 Terraform 顯示「Apply complete!」訊息。

3. 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台的使用者介面中，前往資源頁面，確認 Terraform 已建立或更新資源。

注意：Terraform 範例通常會假設 Google Cloud 專案已啟用必要的 API。

當您提出就地升級要求時，Cloud SQL 會先執行升級前檢查。如果 Cloud SQL 判定執行個體尚未準備好升級，升級要求就會失敗，並顯示訊息，建議您如何解決問題。另請參閱「排解主要版本升級問題」。

注意： Cloud SQL 會自動在預設子版本上佈建執行個體。

在主要版本升級中納入副本

如果主要執行個體有副本，您可以將所有副本納入升級作業。Cloud SQL 可升級主要執行個體的所有副本，包括跨區域副本和串聯式副本。

在主要版本升級中納入副本時，Cloud SQL 會執行下列操作：

1. 檢查主要執行個體和副本的設定，確保執行個體和副本相容，可進行升級。
2. 主要執行個體無法使用。
3. 在升級前備份主要執行個體。
4. 停止所有副本的複製作業。
5. 對主要執行個體執行升級作業。
6. 如果主要執行個體升級成功，主要執行個體就會再次可用，並重新啟動複製作業。
7. Cloud SQL 會在升級後備份主要執行個體。
8. Cloud SQL 會繼續升級所有副本。

即使副本的主要版本升級失敗，主要執行個體仍可繼續使用。

如要在主要版本升級中納入副本，請勿使用Google Cloud 控制台或 Terraform。您只能使用 gcloud CLI 或 Cloud SQL Admin API。

gcloud

1. 開始升級。

   使用 gcloud sql instances patch 指令，並加上 --database-version 和 --include-replicas-for-major-version-upgrade 旗標。

   執行指令前，請先替換下列項目：

   • INSTANCE_NAME：主要執行個體的名稱。
   • DATABASE_VERSION：資料庫主要版本的列舉，必須晚於目前版本。請指定資料庫版本，做為執行個體可升級的主要版本。您可以在升級計畫的第一個步驟中取得這個列舉。 如需資料庫版本列舉的完整清單，請參閱 SqlDatabaseEnums。

   gcloud sql instances patch INSTANCE_NAME \
     --database-version=DATABASE_VERSION \
     --include-replicas-for-major-version-upgrade

   主要版本升級作業需要幾分鐘才能完成。您可能會看到一則訊息，指出作業時間比預期長。您可以忽略這則訊息，或執行 gcloud sql operations wait 指令關閉訊息。升級副本可能需要幾分鐘才能完成。如要查看升級狀態，請按照下列步驟操作：

2. 取得升級作業名稱。

   使用 gcloud sql operations list 指令，並加上 --instance 旗標。

   執行指令前，請將 INSTANCE_NAME 變數替換為執行個體名稱。

   gcloud sql operations list --instance=INSTANCE_NAME

3. 監控升級狀態。

   使用 gcloud sql operations describe 指令。

   執行指令前，請將 OPERATION 變數替換為上一步驟中擷取的升級作業名稱。

   gcloud sql operations describe OPERATION

REST

1. 開始就地升級。

   請使用 instances:patch 方法傳送 PATCH 要求。

   使用任何要求資料之前，請先替換下列變數：

   • PROJECT_ID：專案 ID。
   • INSTANCE_NAME：執行個體的名稱。

   HTTP 方法和網址：

   PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

   JSON 要求主體：

   {
     "databaseVersion": DATABASE_VERSION
     "includeReplicasForMajorVersionUpgrade": true
   }

   • 將 DATABASE_VERSION 替換為資料庫主要版本的列舉，該版本必須晚於目前版本。請指定資料庫版本，做為執行個體可升級的主要版本。您可以在升級計畫的第一個步驟中取得這個列舉。 如需資料庫版本列舉的完整清單，請參閱 SqlDatabaseVersion。
   • 在「includeReplicasForMajorVersionUpgrade」欄位中指定 true。

2. 取得升級作業名稱。

   請將 PROJECT_ID 替換為專案 ID，然後使用 operations.list 方法傳送 GET 要求。

   HTTP 方法和網址：

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

3. 監控升級狀態。

   請使用 GET 要求和 operations.get 方法，並替換下列變數：

   • PROJECT_ID：專案 ID。
   • OPERATION_NAME：在上一個步驟中擷取的升級作業名稱。

   HTTP 方法和網址：

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

自動升級備份

執行主要版本升級時，Cloud SQL 會自動建立兩個隨選備份，稱為升級備份：

• 第一個升級備份是「升級前備份」，會在升級開始前立即建立。您可以使用這個備份，將資料庫執行個體還原至先前版本的狀態。
• 第二個升級備份是「升級後備份」，會在升級後的資料庫執行個體允許新寫入作業後立即建立。

查看備份清單時，升級備份會列為 On-demand 類型。升級備份會加上標籤，方便您快速識別。 舉例來說，如果您從 PostgreSQL 14 升級至 PostgreSQL 15，升級前的備份會標示為 Pre-upgrade backup, POSTGRES_14 to POSTGRES_15.，升級後的備份則會標示為 Post-upgrade backup, POSTGRES_14 to POSTGRES_15.。

與其他隨選備份一樣，升級備份會一直保留，直到您刪除備份或執行個體為止。如果啟用 PITR，就無法在保留期限內刪除升級備份。如要刪除升級備份，請停用 PITR，或等到升級備份超出保留期限。

取消主要版本升級

您可以取消就地主要版本升級作業，但只能在執行個體執行實際版本升級時取消。

注意： 如果您使用唯讀副本，並選擇在主要版本升級中加入副本，就無法取消主要版本升級。

取消期限

主要版本升級作業包含一系列步驟。只能在主要升級階段取消。

1. 初始化：Cloud SQL 準備執行個體及其資源。在這個階段無法取消。

2. 主要升級階段：Cloud SQL 會主動將資料升級至新的主要版本。您只能在這個階段取消。

3. 完成：執行個體完成升級並執行最終驗證。

如要判斷執行個體何時進入可取消階段，請檢查是否有升級記錄。升級記錄位於 projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log

當記錄項目開始出現在這個記錄檔中，表示主要升級階段已啟用，您可以取消作業。

取消

如要取消就地主要版本升級，您需要作業 ID。您必須在 gcloud 或 REST API 指令中指定這個 ID，Cloud SQL 才能知道要取消哪項作業。

您可以使用 gcloud 或 REST API 指令，取消主要版本升級作業。

gcloud

1. 取得升級作業 ID。

   使用 gcloud sql operations list 指令，並加上 --instance 旗標：

   gcloud sql operations list --instance=INSTANCE_NAME
   

   更改下列內容：

   • INSTANCE_NAME：執行個體的名稱。

2. 取消升級。

   使用 gcloud sql operations cancel 指令：

   gcloud sql operations cancel OPERATION_ID
   

   更改下列內容：

   • OPERATION_ID：上一個步驟中擷取的作業 ID。

3. 查看取消狀態。

   使用 gcloud sql operations describe 指令：

   gcloud sql operations describe OPERATION_ID
   

   更改下列內容：

   • OPERATION_ID：在第一個步驟中擷取的作業 ID。

REST v1

1. 取得升級作業 ID。

   將 PROJECT_ID 替換為專案 ID 後，使用 operations.list 方法傳送 GET 要求。

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations
   

   更改下列內容：

   • PROJECT_ID： Google Cloud 專案的 ID。

2. 取消升級。

   使用任何要求資料之前，請先修改下列項目的值：

   • PROJECT_ID： Google Cloud 專案的 ID。
   • OPERATION_ID：上一個步驟中擷取的作業 ID。

   HTTP 方法和網址：

   POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID/cancel

   請展開以下其中一個選項，以傳送要求：

   curl (Linux、macOS 或 Cloud Shell)

   注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

   執行下列指令：

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d "" \
        "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID/cancel"

   PowerShell (Windows)

   注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

   執行下列指令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID/cancel" | Select-Object -Expand Content

   您應該會收到如下的 JSON 回覆：

   回應

   {}
   

   這項 REST API 呼叫不會傳回任何回應。

3. 查看取消狀態。

   使用 GET 要求搭配 operations.list 方法：

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID
   

   更改下列內容：

   • PROJECT_ID： Google Cloud 專案的 ID。
   • OPERATION_ID：在第一個步驟中擷取的作業 ID。

REST v1beta4

1. 取得升級作業 ID。

   將 PROJECT_ID 替換為專案 ID 後，使用 operations.list 方法傳送 GET 要求。

   GET https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations
   

   更改下列內容：

   • PROJECT_ID： Google Cloud 專案的 ID。

2. 取消升級。

使用任何要求資料之前，請先修改下列項目的值：

• PROJECT_ID： Google Cloud 專案的 ID。
• OPERATION_ID：上一個步驟中擷取的作業 ID。

HTTP 方法和網址：

POST https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID/cancel

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID/cancel"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID/cancel" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

回應

{}

這項 REST API 呼叫不會傳回任何回應。

1. 查看取消狀態。

   使用 GET 要求搭配 operations.list 方法：

   GET https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID
   

   更改下列內容：

   • PROJECT_ID： Google Cloud 專案的 ID。
   • OPERATION_ID：在第一個步驟中擷取的作業 ID。

如果取消要求獲准，Cloud SQL 就會停止進行中的升級程序，並開始將執行個體還原至原始狀態。

注意： 取消作業不會立即生效。觸發取消作業後，您無法立即恢復執行個體的存取權。Cloud SQL 會執行必要復原步驟，將系統還原至升級前的狀態，在此期間執行個體仍無法使用。

排解取消問題

問題	疑難排解
錯誤訊息：The operation OPERATION_ID cannot be canceled at the moment. Please retry in approximately 5-10 minutes	升級作業尚未進入可取消的階段。請稍候幾分鐘，然後再次嘗試取消。
錯誤訊息：The operation OPERATION_ID cannot be cancelled as it has passed the cancellable state. The operation is in its final stage and should complete soon.	升級程序已超過可取消的時間範圍。因此無法取消，升級作業應該很快就會完成。
錯誤訊息：You can't cancel operation OPERATION_ID because it isn't in progress.	作業已完成 (無論成功或失敗)，因此無法取消。
錯誤訊息： You can't cancel operation OPERATION_ID because Cloud SQL doesn't support the cancellation of this OPERATION_TYPE operation. The operation OPERATION_ID cannot be cancelled.	如果將錯誤的 OPERATION_ID 傳遞至取消指令，通常會發生這項錯誤，具體來說，就是不支援取消作業類型的 ID。確認您使用的 OPERATION_ID 與要取消的就地資料庫主要版本升級作業相關聯。

如果取消要求已受理，但取消作業失敗，請從程序開始時自動建立的升級前備份還原執行個體。如果問題持續發生，請與Google Cloud 支援團隊聯絡。

完成主要版本升級

完成主要執行個體升級後，請按照下列步驟完成升級：

1. 重新整理資料庫統計資料。

   在主要執行個體上執行 ANALYZE，以便在升級後更新系統統計資料。準確的統計資料可確保 PostgreSQL 查詢規劃工具以最佳方式處理查詢。缺少統計資料可能會導致查詢計畫不佳，進而降低效能並占用過多記憶體。

2. 執行驗收測試。

   執行測試，確保升級後的系統運作正常。

3. 為避免複製串流中斷，請使用開始升級前記錄的資訊，重新建立執行個體的邏輯複製槽 (請參閱「準備主要版本升級」)。

排解主要版本升級問題

如果您嘗試執行無效的升級指令，例如執行個體包含新版本不適用的資料庫旗標，Cloud SQL 就會傳回錯誤訊息。

如果升級要求失敗，請檢查升級要求的語法。如果要求結構有效，請嘗試查看下列建議。

查看錯誤記錄

如果有效的升級要求發生任何問題，Cloud SQL 會將錯誤記錄發布至 projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log。每個記錄項目都包含一個標籤，其中含有執行個體 ID，可協助您找出發生升級錯誤的執行個體。請找出這類升級錯誤並加以解決。

如要查看錯誤記錄，請使用 Google Cloud控制台：

1. 前往 Google Cloud 控制台的「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面。

   前往「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面

2. 點選執行個體名稱，開啟執行個體的「總覽」頁面。

3. 在執行個體「Overview」(總覽) 頁面的「Operations and logs」(作業和記錄) 窗格中，點選「View PostgreSQL error logs」(查看 PostgreSQL 錯誤記錄) 連結。

   「Logs Explorer」頁面隨即開啟。

4. 查看記錄檔，步驟如下：

   • 如要列出專案中的所有錯誤記錄，請在「Log name」(記錄檔名稱) 記錄檔篩選器中選取記錄檔名稱。

   如要進一步瞭解查詢篩選器，請參閱「進階查詢」。

   • 如要篩選單一執行個體的升級錯誤記錄，請在「Search all fields」(搜尋所有欄位) 方塊中輸入下列查詢，並將 DATABASE_ID

   格式如下：project_id:instance_name。

   resource.type="cloudsql_database"
   resource.labels.database_id="DATABASE_ID"
   logName : "projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log"

   舉例來說，如要依據在 buylots 專案中執行的 shopping-db 執行個體篩選升級錯誤記錄，請使用下列查詢篩選器：

    resource.type="cloudsql_database"
    resource.labels.database_id="buylots:shopping-db"
    logName : "projects/buylots/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log"

   您可以查看指定時間範圍內回報的所有記錄，也可以依嚴重性篩選記錄。排解問題時，常見的做法是選取下列篩選條件：

   • 緊急
   • 快訊
   • 重大
   • 錯誤

前置字串為 pg_upgrade_dump 的記錄項目表示發生升級錯誤。例如：

pg_upgrade_dump: error: query failed: ERROR: out of shared memory
HINT: You might need to increase max_locks_per_transaction.

此外，標有 .txt 次要檔案名稱的記錄項目可能會列出其他錯誤，建議您先解決這些錯誤，再嘗試升級。

所有檔案名稱都位於 postgres-upgrade.log 檔案中。如要找出檔案名稱，請查看 labels.FILE_NAME 欄位。

可能含有錯誤、需要解決的檔案名稱包括：

• tables_with_oids.txt: 這個檔案包含以物件 ID (OID) 列出的資料表。請刪除資料表，或修改資料表，使其不使用 OID。
• tables_using_composite.txt:：這個檔案包含使用系統定義複合類型列出的資料表。請刪除資料表，或修改資料表，避免使用這些複合類型。
• tables_using_unknown.txt: 這個檔案包含使用 UNKNOWN 資料類型列出的資料表。請刪除資料表，或修改資料表，使其不使用這個資料類型。
• tables_using_sql_identifier.txt: 這個檔案包含使用 SQL_IDENTIFIER 資料類型列出的資料表。請刪除資料表，或修改資料表，使其不使用這個資料類型。
• tables_using_reg.txt: 這個檔案包含使用 REG* 資料類型列出的資料表 (例如 REGCOLLATION 或 REGNAMESPACE)。請刪除資料表，或修改資料表，使其不使用這類資料類型。
• postfix_ops.txt: 這個檔案包含使用後置 (右一元) 運算子列出的資料表。請刪除資料表，或修改資料表，避免使用這些運算子。

查看個人化記憶

如果執行個體的共用記憶體不足，可能會顯示以下錯誤訊息：ERROR: out of shared memory.。如果資料表超過 10,000 個，就更有可能發生這項錯誤。

嘗試升級前，請將 max_locks_per_transaction 旗標的值設為執行個體中資料表數量的兩倍左右。變更這個旗標的值時，執行個體會重新啟動。

檢查連線容量

如果執行個體的連線容量不足，可能會看到以下錯誤訊息：ERROR: Insufficient connections.

Cloud SQL 建議您根據執行個體中的資料庫數量，提高 max_connections 旗標值。變更這個旗標的值時，執行個體會重新啟動。

檢查是否有不明確的資料欄參照

Cloud SQL 會自動執行升級前檢查，找出依附於系統目錄檢視表 (例如 pg_stat_activity 或 pg_stat_replication) 的使用者定義檢視表。這些系統目錄檢視表的資料欄結構可能會因 PostgreSQL 主要版本而異。如果您的檢視表select *或依賴這些系統檢視表的資料欄順序，則在升級後可能會變得不相容，導致發生錯誤，例如 ERROR: column reference "column_name" is ambiguous。

升級前檢查會檢查依附元件，偵測這類檢視表。如果發現不相容的檢視表，升級程序就會停止，並顯示錯誤訊息。這則訊息會列出各資料庫中不相容的檢視表，您必須加以處理。

錯誤訊息範例

• pg_stat_activity 相關問題：

  Please remove the following usages of views that depend on functions returning
  data types of pg_stat_activity before attempting an upgrade:
  (database: my_db, schema name: public, view name: my_stat_activity_view)

• pg_stat_replication 相關問題：

  Please remove the following usages of views that depend on functions returning
  data types of pg_stat_replication before attempting an upgrade:
  (database: my_db, schema name: public, view name: my_replication_stats_view)

如要解決這類問題並繼續升級，請按照下列步驟操作： 1. 找出升級前檢查錯誤訊息中列出的檢視表。

1. 使用 DROP VIEW view_name; 捨棄這些檢視表。

2. 重試主要版本升級作業。

3. 升級完成後，請重新建立檢視表。請確認新的檢視表定義與目前 PostgreSQL 版本中的系統目錄檢視表結構定義相容。您可能需要明確列出資料欄，而不是使用 select *，以免日後發生問題。

如需更詳細的問題範例和深入分析，請參閱這篇 Stack Overflow 討論。

檢查 CASE 陳述式中的 SRF

如果您將執行個體從 PostgreSQL 9.6 升級，並在 CASE 陳述式中使用傳回集合的函式，可能會看到這則錯誤訊息：ERROR: set-returning functions are not allowed in CASE。發生這個問題的原因是，從第 10 版開始，CASE 陳述式中不得使用傳回集合的函式。

如要解決這個問題並成功升級執行個體，請務必修改所有使用傳回集合函式的 CASE 陳述式，避免使用這些函式，然後再重試升級。以下列舉一些常用的 SRF：

• unnest()
• generate_series()
• array_agg()
• regexp_split_to_table()
• jsonb_array_elements()
• json_array_elements()
• sonb_each()
• json_each()

查看自訂轉換建立的檢視

如果您在自訂轉換上建立檢視表，系統會顯示類似以下的錯誤訊息：ERROR: cannot cast type <type_1> to <type_2>。這是因為自訂 Cast 的權限問題所致。

如要解決這個問題，請將執行個體更新至 [PostgreSQL version].R20240910.01_02

詳情請參閱「自助式維護」。

檢查事件觸發條件擁有權

在 Cloud SQL 中，所有事件觸發條件都必須由具備 cloudsqlsuperuser 角色的使用者擁有。Cloud SQL 會執行升級前檢查，驗證所有事件觸發條件的擁有權。如果事件觸發條件的擁有者不具備 cloudsqlsuperuser 角色，升級程序就會停止，您可能會收到錯誤訊息，例如：

Please ensure that the owners of all event triggers have the cloudsqlsuperuser
role assigned to them before attempting an upgrade:
(database: your_db, triggerName your_trigger, owner: non_super_user)

如要解決這個問題，請將事件觸發條件的擁有者變更為具備 cloudsqlsuperuser 角色的使用者 (例如 postgres)，或將 cloudsqlsuperuser 角色授予目前的擁有者。

如要找出擁有者不具備必要角色的事件觸發條件，請執行下列指令：

SELECT
  t.evtname AS trigger_name,
  r.rolname AS current_owner
FROM pg_event_trigger t
JOIN pg_roles r ON t.evtowner = r.oid
WHERE NOT pg_has_role(r.rolname, 'cloudsqlsuperuser', 'member');

結果會顯示擁有者不具備 cloudsqlsuperuser 角色的所有事件觸發條件。

檢查未記錄資料表中的生成資料欄

如果未記錄的資料表含有產生的資料欄，您可能會看到錯誤訊息 ERROR: unexpected request for new relfilenumber in binary upgrade mode。發生這個問題的原因，是資料表和生成資料欄的序列之間，持久性特徵不一致。

如要解決這個問題，請按照下列步驟操作：

1. 捨棄未記錄的資料表：如果可以，請捨棄與生成資料欄連結的所有未記錄資料表。請務必確認資料遺失問題已妥善解決，再繼續操作。
2. 轉換為永久資料表：請按照下列步驟，暫時將未記錄的資料表轉換為永久資料表：
   1. 將資料表轉換為記錄資料表 ALTER TABLE SET LOGGED;
   2. 升級主要版本
   3. 將資料表轉換回未記錄的資料表 ALTER TABLE SET UNLOGGED

您可以使用下列查詢，找出所有這類資料表：

SELECT
  relnamespace::regnamespace,
  c.relname AS table_name,
  a.attname AS column_name,
  a.attidentity AS identity_type
FROM
  pg_catalog.pg_class c
  JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid
WHERE
  a.attidentity IN ('a', 'd') AND c.relkind = 'r' AND c.relpersistence = 'u'
ORDER BY c.relname, a.attname;

檢查 PostgreSQL 執行個體的自訂旗標

如要升級至 PostgreSQL 執行個體 14 以上版本，請檢查您為執行個體設定的自訂資料庫旗標名稱。這是因為 PostgreSQL 對自訂參數的允許名稱施加了額外限制。

自訂資料庫旗標的第一個字元必須是英文字母 (A-Z 或 a-z)。後續所有字元都可以是英數字元、底線 (_) 特殊字元或錢幣符號 ($) 特殊字元。

移除擴充功能

如果您要升級 Cloud SQL 執行個體，可能會看到以下錯誤訊息：pg_restore: error: could not execute query: ERROR: role "16447" does not exist。

如要解決這個問題，請按照下列步驟操作：

1. 移除 pg_stat_statements 和 pgstattuple 擴充功能。
2. 執行升級。
3. 重新安裝擴充功能。

MVU 作業執行時間較長

主要版本升級作業包含兩項基本工作：

• 預先檢查作業：如果未在三小時內完成，則會傳回逾時錯誤。
• 升級作業：如果未在六小時內完成，則會傳回逾時錯誤。

如果執行個體持續執行 MAJOR_VERSION_UPGRADE 作業的時間超過預期，請檢查 PostgreSQL 錯誤記錄。這可能是由常見問題所造成，例如：

• 資料表、檢視表或索引數量過多
• CPU 或記憶體等資源不足
• 重大交易阻擋資料庫關閉，導致升級程序無法開始。您可以使用 Google Cloud 控制台查看目前的程序。

常見的主要版本升級前檢查錯誤

主要版本升級預先檢查發現的問題分為以下類別：

• 不相容的擴充功能：執行個體上的 PostgreSQL 適用的 Cloud SQL 擴充功能，與新的主要版本不相容。

• 不支援的依附元件：這些依附元件不受新主要版本支援，或需要更新才能與新版本搭配使用。

• 資料庫不相容：資料庫或資料在主要版本升級後可能發生的問題。包括資料庫結構、資料類型、編碼、定序或新版本專屬系統目錄變更的差異。

不相容的擴充功能

下表列出主要版本升級預先檢查可能發現的常見錯誤，這些錯誤與不相容的擴充功能有關：

類型	錯誤示例	解析度
不支援或已淘汰的擴充功能	Your installation contains unsupported extensions for the new version. These extensions must be removed before attempting an upgrade: (database: %s, Extension name: %s)	使用 DROP EXTENSION $extension_name;，從所有使用該擴充功能的資料庫中移除擴充功能。
擴充功能版本不相容	Your installation contains incompatible version extensions. These extensions must be upgraded to a compatible version before attempting an upgrade: (database: %s, Extension name: %s)	請將擴充功能更新至與目標 PostgreSQL 適用的 Cloud SQL 版本相容的版本。如要瞭解相容版本，請參閱「設定 PostgreSQL 適用的 Cloud SQL 擴充功能」。
PostGIS 個未封裝檔案	PostGIS version upgrade has not been completed, unpackaged raster files present. Follow the steps at https://postgis.net/documentation/tips/tip-removing-raster-from-2-3/ to fix before major version upgrade.	清除未封裝的光柵檔案。
PostGIS 項已淘汰函式	PostGIS version upgrade has not been completed, deprecated functions present. Please drop all objects using deprecated functions and upgrade to a different version of PostGIS before major version upgrade.	升級 PostGIS 擴充功能之前，請找出並移除或變更任何使用已淘汰 PostGIS 函式的資料庫物件。
擴充功能擁有權	Please ensure that the owner of the postgres_fdw extension has the cloudsqlsuperuser role assigned to them before attempting an upgrade: (database: my_db, extension name: postgres_fdw, owner: some_user)	使用 ALTER EXTENSION postgres_fdw OWNER TO postgres; 變更擴充功能擁有者。

不支援的依附元件

下表列出與不支援的依附元件相關的常見錯誤，這些錯誤可能會在主要版本升級預先檢查中發現：

類型	錯誤示例	解析度
事件觸發條件擁有權	Please ensure that the owners of all event triggers have the cloudsqlsuperuser role assigned to them before attempting an upgrade: (database: your_db, triggerName your_trigger, owner: non_super_user)	使用 psql 或 Cloud SQL Studio 連線至指定資料庫，並將觸發條件的擁有者變更為 postgres 使用者。
未提交的預先編譯陳述式	Please commit/rollback the following usages of 'Uncommitted Prepared Statements'... (database: my_db, gid: my_prepared_xact)	提交或復原預備陳述式。
已淘汰的旗標	Your installation contains deprecated flags for the new version . These flags must be removed before attempting an upgrade: (database: %s, Flag name: %s)	從執行個體設定中移除資料庫旗標。

資料庫不相容

下表列出與資料格式不相容相關的常見錯誤，這些錯誤可能會在主要版本升級預先檢查時發現：

類型	錯誤示例	解析度
不明資料類型	Please remove the following usages of 'Unknown' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column)	請移除資料欄或資料表，或使用 ALTER TABLE my_table ALTER COLUMN my_column TYPE TEXT; 變更資料表的資料類型。
reg* 資料類型	Please remove the following usages of 'reg*' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column)	請移除資料欄或變更資料類型。
已移除的資料類型	Please remove the following usages of 'sql_identifier' data types before attempting an upgrade: ...	請轉換為 TEXT、timestamptz 或其他合適的資料類型。
​​aclitem 內部格式	Please remove the following usages of 'aclitem' data types before attempting an upgrade: ...	請停止在資料庫資料表定義中使用 aclitem。
系統定義的複合資料類型	Please remove the following usages of 'composite' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column)	請將識別出的資料欄變更為使用使用者定義的複合類型或標準資料類型。系統複合類型在主要版本之間可能不一致。
含有OIDS的表格	Please remove the following usages of tables with OIDs before attempting an upgrade: (database: my_db, relation: my_table)	使用 ALTER TABLE my_table SET WITHOUT OIDS; 更新資料表。
使用者定義的 postfix 運算子	Please remove the following usages of 'postfix operators' before attempting an upgrade: (database: my_db, operation id: 12345, operation namespace: public, operation name: !!, type namespace: public, type name: mytype)	移除自訂 postfix 運算子。您可能需要重寫程式碼，改用前置運算子或函式呼叫。
不相容的多型函式	Please remove the following usages of 'incompatible polymorphic' functions before attempting an upgrade: (database: my_db, object kind: function, object name: public.my_poly_func)	移除或變更函式，以移除不相容的多型函式。這可能表示您需要調整函式簽章或邏輯，才能與 PostgreSQL 適用的 Cloud SQL 14 以上版本搭配使用。
使用者定義的編碼轉換	Please remove the following usages of user-defined encoding conversions before attempting an upgrade: (database: my_db, namespace name: public, encoding conversions name: my_encoding_conv)	移除使用者定義的編碼轉換。升級後，您可能需要使用適用於新版本的簽章重新建立。
檢查是否有不明確的資料欄參照	Cloud SQL 會自動檢查依賴系統目錄檢視表的使用者定義檢視表。這些系統目錄檢視表的資料欄結構可能會在主要版本之間變更。 Please remove the following usages of views that depend on functions returning data types of pg_stat_activity before attempting an upgrade: (database: my_db, schema name: public, view name: my_stat_activity_view)	找出錯誤訊息中列出的檢視表，並使用 DROP VIEW 指令移除。升級後，請重新建立檢視表。
含有生成資料欄或記錄序列的未記錄資料表	Please drop the following usages of 'Unlogged Tables with Logged Sequence' before attempting an upgrade: (database: your_db, table name: problematic_table)	您可以將資料表轉換為 LOGGED，或使用 DROP TABLE 指令移除資料表。升級後重新建立資料表。
修正空白搜尋路徑問題	Please update the search path of the 'll_to_earth' function (database: your_db, search path: )	earthdistance 擴充功能會使用 earth 和 cube types，但不會指定函式的搜尋路徑。使用 ALTER FUNCTION ll_to_earth SET search_path = public; 更新搜尋路徑。

將主要執行個體還原至先前的主要版本

如果升級後的資料庫系統效能不如預期，您可能需要將主要執行個體還原至先前的版本。方法是將升級前的備份還原至 Cloud SQL 復原執行個體，也就是執行升級前版本的新執行個體。

如要將主要執行個體還原至先前的版本，請按照下列步驟操作：

1. 找出升級前的備份。

   請參閱「自動升級備份」。

2. 建立復原執行個體。

   使用 Cloud SQL 在建立升級前備份時執行的主要版本，建立新的 Cloud SQL 執行個體。設定與原始執行個體相同的旗標和執行個體設定。

3. 還原升級前的備份。

   將升級前的備份還原至復原執行個體。這項作業可能需要幾分鐘才能完成。

4. 新增唯讀副本。

   如果使用唯讀副本，請個別新增。

5. 連結應用程式。

   復原資料庫系統後，請更新應用程式，加入復原執行個體及其唯讀副本的詳細資料。您可以繼續在升級前的資料庫版本上提供流量。

常見問題

升級資料庫主要版本時，可能會遇到下列問題。

升級期間是否無法使用執行個體？

可以。Cloud SQL 執行升級作業期間，執行個體會暫時無法使用。

升級需要多久時間？

升級單一執行個體通常會在 10 分鐘內完成。 如果執行個體設定的 vCPU 或記憶體數量較少，升級可能需要較多時間。

如果執行個體託管過多資料庫或資料表，或是資料庫非常龐大，升級作業可能需要數小時，甚至逾時，因為總升級時間與資料庫中的物件數量相對應。如果有多個執行個體需要升級，升級時間會按比例增加。如果升級作業包含副本，則可能需要一小時才能完成，具體時間取決於主要執行個體的副本數量。

我可以監控升級程序的每個步驟嗎？

雖然 Cloud SQL 可讓您監控升級作業是否仍在進行中，但您無法追蹤各項升級作業的個別步驟。

升級後可以取消嗎？

可以，但必須符合特定條件。您可以在主要升級階段取消作業。如要瞭解如何找出可取消的時間範圍，請參閱「取消主要版本升級」。此外，如果主要執行個體包含唯讀副本，則不支援取消作業。如要保留取消功能，升級時請勿加入唯讀副本。

升級期間，我的設定會受到什麼影響？

執行就地主要版本升級時，Cloud SQL 會保留資料庫設定，包括執行個體名稱、IP 位址、明確設定的旗標值和使用者資料。不過，系統變數的預設值可能會變更。舉例來說，PostgreSQL 13 以下版本中 password_encryption 旗標的預設值為 md5。升級至 PostgreSQL 14 後，這個旗標的預設值會變更為 scram-sha-256。

詳情請參閱「設定資料庫旗標」。如果目標版本不再支援特定旗標或值，Cloud SQL 會在升級期間自動移除該旗標，前提是您未設定該旗標。如果您設定的旗標在目標版本中不受支援，則必須先移除旗標，才能升級。

後續步驟

• 瞭解連線至執行個體的選項。
• 瞭解匯入及匯出資料。
• 進一步瞭解如何設定資料庫旗標。