就地升級資料庫主要版本

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：資料庫版本的顯示名稱。

   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"
   }
   
   

   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"
   }
   
   

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

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

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

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

4. 以模擬測試升級。

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

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

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

5. 決定升級時間。

   升級時，執行個體會有一段時間無法使用。請規劃在資料庫活動較少的時段升級。

為主要版本升級做好準備

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

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

   如果 template 和 postgres 資料庫的 LC_COLLATE 值不是 en_US.UTF8，則主要版本升級會失敗。如要修正這個問題，如果任一資料庫的字元集不是 en_US.UTF8，請在升級前將 LC_COLLATE 值變更為 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 Raster 安裝作業」。

   有時，由於物件使用已淘汰的函式，升級至 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() 函式，再執行升級作業。

已知限制

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

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

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

  注意： PostgreSQL 適用的 Cloud SQL 16 以上版本不支援 pg_squeeze 擴充功能。

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

  注意： 在 PostgreSQL 16 以上版本中，vacuum_defer_cleanup_age 標記已淘汰，force_parallel_mode 標記則重新命名為 debug_parallel_query。

執行主要版本升級

您可以升級單一 Cloud SQL 執行個體的主要版本，也可以升級主要執行個體的主要版本，並將所有備用資源 (包括連鎖備用資源和跨區域備用資源) 納入升級範圍。

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

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

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

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

控制台

1. 前往 Google Cloud 控制台的「Cloud SQL Instances」頁面。

   前往 Cloud SQL 執行個體

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

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

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

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. 開始直接升級。

   使用 PATCH 要求和 instances: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. 取得升級作業名稱。

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

   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 Cloud的 Terraform 供應商，版本為 4.34.0 以上。

resource "google_sql_database_instance" "instance" {
  name             = "postgres-instance"
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

套用變更

如要在 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 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

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

刪除變更

如要刪除變更，請按照下列步驟操作：

1. 如要停用防刪除功能，請在 Terraform 設定檔中將 deletion_protection 引數設為 false。

   deletion_protection =  "false"

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

   terraform apply

3. 執行下列指令，並在提示中輸入 yes，移除先前透過 Terraform 設定套用的資源：

   terraform destroy

提出就地升級要求後，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. 開始直接升級。

   使用 PATCH 要求和 instances: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. 取得升級作業名稱。

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

   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. 重新整理資料庫統計資料。

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

2. 執行驗收測試。

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

排解主要版本升級問題

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

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

查看升級前檢查失敗情形

升級前檢查失敗是指 Cloud SQL 在升級前驗證或驗證程序中偵測到的問題或錯誤。這些失敗情況會在實際升級程序開始前發生，目的是找出可能影響升級成功率的潛在問題或不相容情況。

系統會顯示下列類別的升級前檢查失敗情形：

• 不相容的擴充功能：偵測與執行個體目的地版本不相容的 PostgreSQL 擴充功能。
• 不支援的依附元件：找出不再支援或需要更新的依附元件。
• 資料格式不相容：確認因各種因素造成的資料不一致，包括版本專屬資料結構的差異、編碼和排序規則的變更、資料類型的修改，以及系統目錄的調整。

下表列出升級前檢查失敗的項目及其錯誤訊息：

升級前檢查失敗	錯誤訊息
Cloud SQL 偵測到不明資料類型。	Please remove the following usages of 'Unknown' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
升級至 PostgreSQL 12 以上版本時，Cloud SQL 會偵測 'sql_identifier' 資料型別。	Please remove the following usages of 'sql_identifier' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
Cloud SQL 會偵測 reg* 資料類型。	Please remove the following usages of 'reg*' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
Cloud SQL 偵測到 postgres 資料庫的 LC_COLLATE 值是 en_US.UTF8 以外的字元集。	Please change the 'LC_COLLATE' value of the postgres database to 'en_US.UTF8' before attempting an upgrade
Cloud SQL 會偵測含有物件 ID (OID) 的資料表。	Please remove the following usages of tables with OIDs before attempting an upgrade: (database: db_name, relation: rel_name)
Cloud SQL 會偵測複合資料類型。	Please remove the following usages of 'composite' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
Cloud SQL 會偵測使用者定義的後置運算子。	Please remove the following usages of 'postfix operators' before attempting an upgrade: (database: db_name, operation id: op_id, operation namespace: op_namespace, operation name: op_name, type namespace: type_namespace, type name: type_name)
Cloud SQL 會偵測不相容的多型函式。	Please remove the following usages of 'incompatible polymorphic' functions before attempting an upgrade: (database: db_name, object kind: obj_kind, object name: obj_name)
Cloud SQL 會偵測使用者定義的編碼轉換。	Please remove the following usages of user-defined encoding conversions before attempting an upgrade: (database: db_name, namespace name: namespace_name, encoding conversions name: encod_name)
Cloud SQL 偵測到函式 ll_to_earth 的搜尋路徑為空白	Please update the search path of the 'll_to_earth' function
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.

修正搜尋路徑空白的問題

這是因為 earthdistance 擴充功能使用 earth 和 cube 類型，但未指定函式的搜尋路徑。您必須指定這個路徑，升級程序需要用到。

如要解決這個問題，請執行下列查詢，修正 ll_to_earth 函式的搜尋路徑： ALTER FUNCTION ll_to_earth SET search_path = public;

查看錯誤記錄

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

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

1. 前往 Google Cloud 控制台的「Cloud SQL Instances」頁面。

   前往 Cloud SQL 執行個體

2. 如要開啟執行個體的「總覽」頁面，請按一下執行個體名稱。

3. 在執行個體「總覽」頁面的「作業和記錄」窗格中，按一下「查看 PostgreSQL 錯誤記錄」連結。

   「Logs Explorer」(記錄檔探索工具) 頁面隨即開啟。

4. 查看記錄的方式如下：

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

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

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

   專案 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 旗標值增加執行個體中的資料庫數量。變更此旗標的值時，執行個體會重新啟動。

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

如果檢視區塊中有不明確的資料欄參照，您可能會看到以下錯誤訊息：ERROR: column reference "<column_name>" is ambiguous。如果新版 PostgreSQL 變更了系統目錄檢視區塊 (例如 pg_stat_activity 和 pg_stat_replication) 的結構，就會發生這個問題。這可能會導致依賴欄順序的自訂檢視中斷。

如要檢查這則錯誤訊息，請在查詢編輯器中新增以下查詢： textPayload =~ "ERROR: column reference .+ is ambiguous at character \d+"

解決這個問題的方法如下：

1. 調整自訂檢視畫面。

   更新自訂檢視區塊中的資料欄參照，以符合目標 PostgreSQL 版本中新的系統目錄檢視區塊 (例如 pg_stat_activity 和 pg_stat_replication) 定義。

2. 重新建立檢視畫面。

   執行主要版本升級前，請先捨棄自訂檢視區塊。升級完成後，請重新建立檢視區塊，確保這些檢視區塊與新結構相容。

如需問題的詳細範例和深入洞察資料，請參閱這篇 Stack Overflow 討論。

檢查 CASE 陳述式中的 SRF

如果您是從 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>。 這是因為自訂建立的投放內容有權限問題。

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

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

檢查事件觸發擁有權

如果事件觸發程序屬於沒有 cloudsqlsuperuser 角色的使用者，您可能會收到類似 ERROR: permission denied to change owner of event trigger "<trigger_name>" 的錯誤訊息。升級期間嘗試重新建立這些觸發條件時，發生權限問題，導致這個問題。您可以在查詢編輯器中加入下列查詢，檢查是否有這則錯誤訊息： textPayload =~ "ERROR: permission denied to change owner of event trigger .+ "

如要解決這個問題，請驗證執行個體中所有事件觸發條件的擁有權。 請確認每個觸發程序的擁有者都是 cloudsqlsuperuser。如有任何觸發程序屬於其他使用者，請先將擁有權更新為 cloudsqlsuperuser，再嘗試再次升級。您可以使用下列查詢變更擁有權： ALTER EVENT TRIGGER <trigger_name> OWNER TO <cloudsqlsuperuser>;

您可以使用下列查詢，取得事件觸發條件清單和擁有者詳細資料： SELECT evtname AS trigger_name, evtowner::regrole AS owner FROM pg_event_trigger;

檢查未記錄資料表產生的資料欄

如果未記錄的表格產生了資料欄，您可能會看到 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. 重新安裝擴充功能。

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

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

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

1. 找出升級前的備份。

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

2. 建立復原執行個體。

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

3. 還原升級前的備份。

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

4. 新增唯讀備用資源。

   如果您使用唯讀備用資源，請個別新增。

5. 連結應用程式。

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

常見問題

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

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

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

升級需要多久時間？

升級單一執行個體通常不到 10 分鐘。 如果執行個體設定的 vCPU 或記憶體數量較少，升級作業可能需要較長時間。

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

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

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

升級作業開始後，可以取消嗎？

很抱歉，升級作業開始後就無法取消。如果升級失敗，Cloud SQL 會自動將執行個體還原至先前的版本。

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

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

詳情請參閱「設定資料庫標記」。如果目標版本不再支援特定旗標或值，Cloud SQL 會在升級期間自動移除該旗標。

後續步驟

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