執行主要版本資料庫就地升級

如要將 AlloyDB for PostgreSQL 叢集升級至較高的 PostgreSQL 主要版本，同時保留現有的執行個體名稱、IP 位址和連線字串，您可以規劃、驗證及執行就地主要版本升級。如要瞭解就地主要版本升級用途、工作流程階段和自動備份，請參閱「資料庫就地主要版本升級總覽」。

規劃資料庫主要版本升級

請按照下列步驟規劃資料庫主要版本升級：

1. 找出目前的資料庫主要版本。

   控制台

   1. 前往 Google Cloud 控制台的「Clusters」(叢集) 頁面。

      前往「Clusters」(叢集) 頁面

   2. 從清單中選取叢集。「Overview」(總覽) 頁面隨即顯示。

   3. 在「Version」(版本) 欄位中，找出資料庫主要版本。

   gcloud

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

   執行下列指令，取得叢集詳細資料，包括目前的主要版本：

   gcloud alloydb clusters describe CLUSTER_ID --region=REGION

   請依指示取代下列項目：

   • CLUSTER_ID：叢集 ID
   • REGION：叢集位置或區域

   REST v1beta

   執行下列要求，取得叢集詳細資料，包括目前的主要版本：

   GET https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID

   請依指示取代下列項目：

   • CLUSTER_ID：叢集 ID
   • PROJECT_ID：專案 ID
   • REGION：叢集位置或區域

   如要傳送要求，請使用下列其中一個選項：

   curl (Linux、macOS或 Cloud Shell)

   執行下列指令：

      curl -X GET \
            -H "Authorization: Bearer $(gcloud auth print-access-token)" \
            -H "Content-Type: application/json; charset=utf-8" \
            "https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID"
      

   PowerShell (Windows)

   執行下列指令：

      $cred = gcloud auth print-access-token
      $headers = @{ "Authorization" = "Bearer $cred" }
   
      Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID| Select-Object -Expand Content
      

2. 請從下表找出目標資料庫的主要版本。如需 AlloyDB 支援的資料庫版本完整清單，請參閱「資料庫版本和版本政策」。

   來源主要版本	支援的目標主要版本
   POSTGRES_14	POSTGRES_15 POSTGRES_16 POSTGRES_17 POSTGRES_18
   POSTGRES_15	POSTGRES_16 POSTGRES_17 POSTGRES_18
   POSTGRES_16	POSTGRES_17 POSTGRES_18
   POSTGRES_17	POSTGRES_18

3. 查看各資料庫主要版本提供的功能。

   • PostgreSQL 18
   • PostgreSQL 17
   • PostgreSQL 16
   • PostgreSQL 15
   • PostgreSQL 14

4. 找出需要解決的不相容問題。新的主要版本可能會導入不相容的變更，您可能需要修改應用程式程式碼、結構定義或資料庫設定。

5. 在正式版叢集上開始主要版本升級之前，建議您複製叢集，並在複製的叢集上測試主要版本升級。

   除了確認升級作業成功完成外，也請執行測試，確保應用程式在升級後的叢集上運作正常。

準備叢集，以便升級主要版本

如要連線至資料庫，請使用下列其中一種方法：

• AlloyDB Studio
• psql
• 其他連線方式

1. 如果 AlloyDB 叢集是邏輯複製來源，請停用下游訂閱項目，並捨棄所有邏輯複製運算單元。升級後，您可以重新啟用訂閱項目，並重新建立邏輯複製運算單元。如果 AlloyDB 執行個體只是邏輯複製目標，則不需要執行這些步驟。如要停用訂閱項目並捨棄邏輯複製運算單元，請按照下列步驟操作：

   1. 停用訂閱者或下游複製目標上的每個下游訂閱項目。請勿停用升級中 AlloyDB 執行個體的下游訂閱項目：

      • 如果您使用的是 pglogical，請執行下列指令：

        SELECT * FROM
        pglogical.alter_subscription_disable(SUBSCRIPTION_NAME, immediate);
        

        將查詢中的 SUBSCRIPTION_NAME 替換為現有訂閱項目名稱。如需立即停用訂閱項目，請將 immediate 參數的值設為 true。預設值為 false，且訂閱會在目前交易結束後停用。

        例如：

        postgres=> SELECT * FROM pglogical.alter_subscription_disable('test_sub',true);
        alter_subscription_disable
        ----------------------------
        t
        (1 row)
        

      • 如果您使用的不是 pglogical 擴充功能，請執行下列指令：

        ALTER SUBSCRIPTION SUBSCRIPTION_NAME DISABLE;
        

   2. 執行下列指令，捨棄 AlloyDB 主要執行個體上的所有邏輯複製運算單元：

      SELECT pg_drop_replication_slot(REPLICATION_SLOT_NAME) FROM pg_replication_slots WHERE slot_type = 'logical';
      

      將查詢中的 REPLICATION_SLOT_NAME 替換為複製運算單元的名稱。

2. 管理 PostgreSQL 擴充功能。詳情請參閱「設定資料庫擴充功能」。

   升級前檢查會偵測擴充功能不相容問題，並在記錄中顯示這些違規事項，以及建議採取的行動。詳情請參閱「查看升級前檢查失敗」。

   您可能需要執行下列操作：

   1. 捨棄目標版本不再支援的任何擴充功能。

   2. 將 PostGIS 和相關擴充功能 (address_standardizer、address_standardizer_data_us、postgis_raster、postgis_sfcgal、postgis_tiger_geocoder 和 postgis_topology) 升級至目標 PostgreSQL 版本支援的版本。詳情請參閱「PostGIS 擴充功能」。下表列出各個 PostgreSQL 主要版本支援的最低 PostGIS 擴充功能版本：

      PostgreSQL 版本	PostGIS 最低支援版本
      PG14	3.1
      PG15	3.2
      PG16	3.4
      PG17	3.5
      PG18	3.6

      舉例來說，如果您的 PostGIS 版本是 3.1.x，且想從 POSTGRES 14 升級至 POSTGRES 16，請使用下列指令升級 PostGIS 擴充功能：

      ALTER EXTENSION postgis UPDATE TO '3.4.0';
      SELECT PostGIS_Version();
      

3. 確認叢集不含孤立角色成員資格。就地升級主要版本時，如果原始授予者已不存在，系統不會保留角色成員資格。如果任何叢集在 pg_auth_members 目錄中含有孤立成員資格，這些角色成員資格會在升級後遺失。

   如要偵測孤立成員資格，請執行下列查詢：

   SELECT roleid::regrole, member::regrole, grantor::regrole
   FROM pg_auth_members
   WHERE grantor::regrole::text ~ '^[0-9]+$';
   

   如果查詢傳回任何資料列，請先重新建立角色成員資格，再升級叢集。針對每個孤立成員資格，撤銷權限並立即重新授予。這會將成員資格與目前有效的授權者 (例如 alloydbadmin) 建立關聯。

   針對每個孤立成員資格，執行下列交易區塊：

   BEGIN;
   REVOKE ROLE_NAME FROM MEMBER_NAME;
   GRANT ROLE_NAME TO MEMBER_NAME;
   COMMIT;
   

   將 ROLE_NAME 和 MEMBER_NAME 替換為查詢結果中的角色。

4. 執行下列查詢，並檢查每個資料庫的 datallowconn 欄位，確認除了 template0 以外，每個資料庫都允許連線：

   SELECT datname,datallowconn from pg_database;
   

   如果 datallowconn 欄位的值為 t，表示允許連線。f 值表示無法建立連線。template0 資料庫不得允許連線。

   如要允許連線至資料庫，請執行下列指令：

   ALTER DATABASE DATABASE_NAME WITH ALLOW_CONNECTIONS = true;
   

5. 執行下列指令，確認 template1 是範本資料庫：

   SELECT datname, datistemplate FROM pg_database WHERE datname = 'template1';
   

   如果 datistemplate 為 f，請執行下列指令，將其設為 true：

   ALTER DATABASE template1 WITH IS_TEMPLATE true;
   

就地升級叢集主要版本

資料庫就地主要版本升級作業可能需要 40 分鐘到 48 小時才能完成，具體時間取決於資料庫大小、結構定義大小，以及叢集中的讀取集區執行個體數量等因素。主要執行個體的停機時間通常為 20 分鐘到一小時，主要取決於資料庫結構定義。

提出就地主要版本升級要求時，AlloyDB 會先執行升級前檢查。如果 AlloyDB 判定叢集尚未準備好升級主要版本，要求就會失敗。詳情請參閱「排解主要版本就地升級問題」。

如要就地升級資料庫主要版本，請按照下列步驟操作：

gcloud alloydb clusters upgrade CLUSTER_ID --region=REGION --version=DATABASE_VERSION --async

gcloud alloydb clusters upgrade my-cluster --region=us-central1 --version=POSTGRES_16 --async

PATCH https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:upgrade

{
  "version": "DATABASE_VERSION"
}

{
"version": "POSTGRES_16"
}

To upgrade an instance within your database cluster to a PostgreSQL version, use a [Terraform resource](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/alloydb_instance) and set the `database_version` to a [supported target major version](/alloydb/docs/upgrade-db-inplace-major-version#plan-upgrade).

```none
resource "google_alloydb_instance" "default" {
cluster       = google_alloydb_cluster.default.name
instance_id   = "alloydb-instance"
instance_type = "PRIMARY"

machine_config {
  cpu_count = 2
}

depends_on = [google_service_networking_connection.vpc_connection]
}

resource "google_alloydb_cluster" "default" {
  cluster_id = "alloydb-cluster"
  location   = "us-central1"
  network_config {
    network = google_compute_network.default.id
  }
  database_version = "POSTGRES_16"

  initial_user {
    password = "alloydb-cluster"
  }
}

data "google_project" "project" {}

resource "google_compute_network" "default" {
  name = "alloydb-network"
}

resource "google_compute_global_address" "private_ip_alloc" {
  name          =  "alloydb-cluster"
  address_type  = "INTERNAL"
  purpose       = "VPC_PEERING"
  prefix_length = 16
  network       = google_compute_network.default.id
}

resource "google_service_networking_connection" "vpc_connection" {
  network                 = google_compute_network.default.id
  service                 = "servicenetworking.googleapis.com"
  reserved_peering_ranges = [google_compute_global_address.private_ip_alloc.name]
}
```

To learn how to apply or remove a Terraform configuration, see [Basic Terraform commands](/docs/terraform/basic-commands).

監控叢集主要版本升級作業

資料庫主要版本就地升級作業開始後，您可以使用 Google Cloud 控制台、gcloud CLI 或 REST API 監控升級狀態。

升級作業回應

UpgradeCluster 作業回應包含下列內容：

• status：整體升級作業的狀態。可能的值為 SUCCESS、FAILED 和 PARTIAL_SUCCESS.
• message：提供升級作業結果的簡短摘要。
• clusterUpgradeDetails：升級中叢集的升級詳細資料。這個欄位是陣列。AlloyDB 僅允許單一叢集升級，因此只會包含一個項目。
  • name：叢集的完整名稱。
  • upgradeStatus：叢集升級狀態。可能的值為 SUCCESS、FAILED、PARTIAL_SUCCESS。PARTIAL_SUCCESS 表示一或多個讀取集區執行個體無法升級。
  • clusterType：叢集類型。AlloyDB 只能升級單一 PRIMARY 叢集。這個類型一律必須是 PRIMARY。
  • databaseVersion：叢集目前的資料庫版本。
  • stageInfo：核心升級階段的相關資訊。
    • status：SUCCESS或FAILED
    • logs_url：階段產生的記錄連結。如果階段不會產生記錄，則會留空。
  • instanceUpgradeDetails：叢集中所有執行個體的升級資訊。
    • name：執行個體的完整名稱
    • upgradeStatus：SUCCESS或FAILED
    • instanceType：PRIMARY或READ_POOL

以下是升級作業回應範例：

"response": {
  "@type": "type.googleapis.com/google.cloud.alloydb.v1alpha.UpgradeClusterResponse",
  "status": "SUCCESS",
  "message": "Cluster upgraded successfully.",
  "clusterUpgradeDetails": [
    {
      "name": "projects/1234/locations/us-central1/clusters/abc",
      "upgradeStatus": "SUCCESS",
      "clusterType": "PRIMARY",
      "databaseVersion": "POSTGRES_16",
      "stageInfo": [
        {
          "stage": "ALLOYDB_PRECHECK",
          "status": "SUCCESS",
          "logsUrl": "https://console.cloud.google.com/logs/query..."
        },
        {
          "stage": "PG_UPGRADE_CHECK",
          "status": "SUCCESS",
          "logsUrl": "https://console.cloud.google.com/logs/query..."
        },
        {
          "stage": "PRIMARY_INSTANCE_UPGRADE",
          "status": "SUCCESS",
          "logsUrl": "https://console.cloud.google.com/logs/query..."
        },
        {
          "stage": "READ_POOL_INSTANCES_UPGRADE",
          "status": "SUCCESS",
        }
      ],
      "instanceUpgradeDetails": [
        {
          "name": "projects/1234/locations/us-central1/clusters/abc/instances/primary",
          "upgradeStatus": "SUCCESS",
          "instanceType": "PRIMARY",
        },
        {
          "name": "projects/1234/locations/us-central1/clusters/abc/instances/read1",
          "upgradeStatus": "SUCCESS",
          "instanceType": "READ_POOL",
        },
        {
          "name": "projects/1234/locations/us-central1/clusters/abc/instances/read2",
          "upgradeStatus": "SUCCESS",
          "instanceType": "READ_POOL",
        }
      ]
    }
  ]
}

查看 AlloyDB 升級記錄

AlloyDB 會將所有升級記錄發布至 postgres_upgrade 記錄名稱。

如要查看升級相關記錄，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的 segment「Logs Explorer」頁面：

   前往「Logs Explorer」(記錄檔探索工具)

   如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

2. 選取「alloydb.googleapis.com/postgres_upgrade」做為記錄檔名稱。這會轉譯為查詢 "logName="projects/PROJECT_ID/logs/alloydb.googleapis.com%2Fpostgres_upgrade"。

3. 使用下列標籤篩選記錄：

   標籤	說明
   LOG_TYPE	產生記錄的升級階段。可能的值為 ALLOYDB_PRECHECK、PG_UPGRADE_CHECK 和 PG_UPGRADE。
   OPERATION_NAME	升級作業的完整名稱。
   FILE_NAME	僅適用於 pg_upgrade_check 和 pg_upgrade 記錄，且對應至 pg_upgrade 公用程式產生的記錄檔。

下列查詢範例會傳回特定作業的 AlloyDB 預先檢查升級記錄：

logName="projects/project1234/logs/alloydb.googleapis.com%2Fpostgres_upgrade"
labels.LOG_TYPE="ALLOYDB_PRECHECK"
labels.OPERATION_NAME="projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID"

如要進一步瞭解升級檢查，請參閱「資料庫就地升級主要版本總覽」。

查看叢集的升級記錄

如果您不知道作業 ID，且作業已過期，請按照下列步驟查看叢集的升級記錄：

1. 前往 Google Cloud 控制台的 segment「Logs Explorer」頁面：

   前往「Logs Explorer」(記錄檔探索工具)

   如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

2. 查詢叢集的 AlloyDB 預先檢查記錄。

   logName="projects/PROJECT_ID/logs/alloydb.googleapis.com%2Fpostgres_upgrade"
   labels.LOG_TYPE="ALLOYDB_PRECHECK"
   resource.labels.cluster_id=CLUSTER_ID
   

3. 從 OPERATION_NAME 記錄標籤中找出 Operation_ID。

   在以下範例中，OPERATION_NAME 的 Operation_ID 為 operation-1728225968201-623cff6ed1e02-e34b7191-3cd92013。

   labels.OPERATION_NAME="projects/myproject/locations/us-central1/operations/operation-1728225968201-623cff6ed1e02-e34b7191-3cd92013"
   

4. 查詢特定作業的所有 postgres_upgrade 記錄。

   logName="projects/production-1/logs/alloydb.googleapis.com%2Fpostgres_upgrade"
   labels.OPERATION_NAME="operation-1728225968201-623cff6ed1e02-e34b7191-3cd92013"
   

取消資料庫就地升級主要版本

您可以透過 Google Cloud 控制台、gcloud CLI 或 REST API，取消進行中的主要版本升級作業。

找出作業 ID

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

主要執行個體升級作業達到特定階段後，就無法取消。

啟動就地主要版本升級作業時，系統會在回應的 name 欄位中傳回作業 ID。請參閱回應範例。

您也可以在 AlloyDB 叢集上發出 operations.list 呼叫，找出作業 ID。

取消升級

如要取消就地升級主要版本，請按照下列步驟操作：

gcloud alloydb operations cancel OPERATION_ID

POST https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/operations/OPERATION_ID:cancel

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

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

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

完成就地升級主要版本

如要完成主要版本升級，請使用 AlloyDB Studio、psql 或其他連線方法連線至 AlloyDB 執行個體。

如果您使用的是非 AlloyDB 系統，請參閱系統說明文件，瞭解連線操作說明。

升級叢集後，請按照下列步驟完成升級：

1. 如果您先前停用了 pglogical，請重新啟用 pglogical 複製功能。啟用 pglogical 複製功能後，系統會自動建立必要的複製運算單元。

   1. 使用下列指令，捨棄目的地副本上的 pglogical 訂閱項目：

        select pglogical.drop_subscription(subscription_name name);
      

      將 name 替換為現有訂閱項目的名稱。例如：

      postgres=> select pglogical.drop_subscription(subscription_name:= 'test_sub');
      -[ RECORD 1 ]-----+--
      drop_subscription |1
      

   2. 請將下列連線資訊提供給 AlloyDB 主要執行個體，在目的地或副本上重新建立 pglogical 訂閱項目：

        SELECT pglogical.create_subscription(
        subscription_name :='test_sub',<br>
        provider_dsn := 'host=primary-ip port=5432 dbname=postgres user=replication_user password=replicapassword'
        );
      

   3. 使用下列指令檢查訂閱項目狀態：

        SELECT * FROM pglogical.show_subscription_status('test_sub');
      

   4. 執行寫入交易，並確認目的地顯示變更，藉此測試複製作業。

2. 手動更新升級後資料庫中的資料庫擴充功能。

   雖然主要版本升級會自動在執行個體的基礎軟體上安裝最新的擴充功能二進位檔，但不會自動更新擴充功能的資料庫目錄。您必須手動更新擴充功能，確保使用的是最新支援版本。如需操作說明，請參閱「更新擴充功能」。

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

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

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

5. 在 Google Cloud 控制台的叢集「Overview」(總覽) 頁面，確認資料庫就地升級後的主要版本。

還原至上一個主要版本

如果升級後的資料庫系統效能不如預期，您可能需要還原至升級前的狀態。您可以透過升級前備份 (AlloyDB 在升級過程中自動建立的備份，或現有的升級前備份) 進行還原，建立具有升級前狀態的新叢集。

如要還原至升級前的狀態，請按照下列步驟操作：

1. 找出要還原的升級前備份。在升級過程中，AlloyDB 會自動建立升級前備份，前置字串為 pre-upgrade-bkp。詳情請參閱「查看備份清單」。

2. 從升級前的備份啟動還原作業，這會建立一個採用舊版 PostgreSQL 的新叢集。詳情請參閱「從儲存的備份還原叢集」。

3. 連結應用程式。更新應用程式，加入還原叢集及其唯讀副本的詳細資料。您可以在還原的叢集上繼續提供流量。

您也可以執行時間點復原，將資料庫還原至升級前的時間點。詳情請參閱「使用時間點復原 (PITR)」。

限制

下列限制會影響 AlloyDB 的就地主要版本升級：

後續步驟

• 進一步瞭解資料庫就地主要版本升級。
• 排解就地升級主要版本的問題。
• 瞭解資料庫就地升級主要版本錯誤。