就地升級資料庫主要版本

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

本頁面說明如何升級資料庫主要版本，方法是升級 Cloud SQL 執行個體，而不是遷移資料。

簡介

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

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

規劃主要版本升級作業

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)

   執行下列指令：

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

   PowerShell (Windows)

   執行下列指令：

   $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)

   執行下列指令：

   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)

   執行下列指令：

   $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 光柵安裝作業」。

   有時，由於物件使用已淘汰的函式，因此無法完成升級至 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, 000 萬個大型物件，升級作業就會失敗。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 擴充功能」。

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

執行主要版本升級

您可以升級單一 Cloud SQL 執行個體的主要版本，也可以升級主要執行個體的主要版本，並在升級中納入所有備用資源，包括階層備用資源和跨區域備用資源。

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

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

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

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
}

當您提出就地升級要求時，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。

自動備份升級

執行主要版本升級時，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 擴充功能。
• 不支援的依附元件：找出不再支援或需要更新的依附元件。
• 資料格式不相容：驗證因各種因素而產生的資料不一致情形，包括版本專屬資料結構的差異、編碼和對照的變更、資料類型的修改，以及系統目錄的調整。

下表列出升級前檢查失敗的情況和錯誤訊息：

修正空白搜尋路徑問題

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

如要解決這個問題，請執行以下查詢，修正 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，方便您找出發生升級錯誤的執行個體。請找出這類升級錯誤並加以修正。

如要查看錯誤記錄，請按照下列步驟操作：

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

   前往 Cloud SQL 執行個體

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

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

   「Logs Explorer」頁面隨即開啟。

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

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

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

   • 如要篩選單一執行個體的升級錯誤記錄，請在「Search all fields」方塊中輸入以下查詢，並在 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 陳述式中使用 set 傳回函式，您可能會看到此錯誤訊息 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 會在升級期間自動移除該旗標。

後續步驟

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