データベースのメジャー バージョンをインプレースでアップグレードする

このページでは、AlloyDB for PostgreSQL クラスタのデータベースのメジャー バージョンをインプレースでアップグレードする方法について説明します。データベースのメジャー バージョンのインプレース アップグレードのユースケース、ワークフロー、自動バックアップについては、データベースのメジャー バージョンのインプレース アップグレードの概要をご覧ください。

データベースのメジャー バージョンのアップグレードを計画する

データベースのメジャー バージョンのアップグレードを計画する手順は次のとおりです。

1. 現在のデータベースのメジャー バージョンを確認します。

   コンソール

   1. Google Cloud コンソールで [クラスタ] ページに移動します。

      [クラスタ] に移動

   2. リストからクラスタを選択します。[概要] ページが表示されます。

   3. [バージョン] フィールドでデータベースのメジャー バージョンを確認します。

   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_15	POSTGRES_16

3. データベースの各メジャー バージョンで提供される機能を確認します。

   • PostgreSQL 16
   • PostgreSQL 15
   • PostgreSQL 14

4. 対処する必要のある互換性の問題を確認します。新しいメジャー バージョンで互換性のない変更が導入され、アプリケーション コード、スキーマ、データベース設定の変更が必要になる場合があります。

5. 本番環境クラスタでメジャー バージョンのアップグレードを始める前に、クラスタのクローンを作成し、そのクローンでメジャー バージョンのアップグレードをテストすることをおすすめします。

   アップグレードが正常に完了することを検証するだけでなく、アップグレードされたクラスタでアプリケーションが期待どおりに動作することをテストします。

メジャー バージョンのアップグレードを行うクラスタの準備

次のいずれかの方法でデータベースに接続します。

• AlloyDB Studio
• psql
• その他の接続方法

1. クロスリージョン レプリカを削除またはプロモートします。データベースのメジャー バージョンのインプレース アップグレードは、クロスリージョン レプリカに対応していません。詳細については、クロスリージョン レプリケーションをご覧ください。

2. 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 は、レプリケーション スロットの名前に置き換えます。

3. 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

      たとえば、PostGIS のバージョンが 3.1.x で、POSTGRES 14 から POSTGRES 16 にアップグレードする場合は、次のコマンドを使用して PostGIS 拡張機能をアップグレードします。

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

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 分から 1 時間です。この時間は、主にデータベース スキーマによって異なります。

メジャー バージョンのインプレース アップグレードをリクエストすると、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"
}

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

クラスタのメジャー バージョンのアップグレードをモニタリングする

データベースのメジャー バージョンのインプレース アップグレードが開始すると、Google Cloud コンソール、gcloud CLI、または REST API でアップグレードのステータスをモニタリングできます。

アップグレード オペレーションのレスポンス

UpgradeCluster のオペレーション レスポンスには次のものが含まれます。

• status: アップグレード オペレーション全体のステータス。値は SUCCESS、FAILED、PARTIAL_SUCCESS. のいずれかです。
• message: アップグレード オペレーションの結果の概要。
• clusterUpgradeDetails: アップグレードされるクラスタのアップグレードの詳細。このフィールドは配列です。AlloyDB では、クラスタのアップグレードは 1 回のみ許可されるため、エントリは 1 つだけです。
  • name: クラスタの完全修飾名。
  • upgradeStatus: クラスタ アップグレードのステータス。値は SUCCESS、FAILED、PARTIAL_SUCCESS のいずれかです。PARTIAL_SUCCESS は、1 つ以上のリードプール インスタンスをアップグレードできないことを意味します。
  • clusterType: クラスタのタイプ。AlloyDB では、1 つの 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 は、すべてのアップグレード ログを postgres_upgrade という名前のログに公開します。

アップグレード関連のログを表示するには、次の操作を行います。

1. Google Cloud コンソールで、[ログ エクスプローラ] ページに移動します。

   [ログ エクスプローラ] に移動

   検索バーを使用してこのページを検索する場合は、小見出しが [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 コンソールで、[ログ エクスプローラ] ページに移動します。

   [ログ エクスプローラ] に移動

   検索バーを使用してこのページを検索する場合は、小見出しが [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 が必要です。キャンセルするオペレーションを AlloyDB が認識できるように、この ID を gcloud CLI または REST API コマンドで指定する必要があります。

プライマリ インスタンスのアップグレードが特定の時点に達した後は、アップグレードをキャンセルできません。

メジャー バージョンのインプレース アップグレードを開始すると、オペレーション ID がレスポンスの name フィールドに返されます。レスポンスの例をご覧ください。

オペレーション ID は、AlloyDB クラスタに対する operations.list 呼び出しで確認することもできます。

アップグレードをキャンセルする

メジャー バージョンのアップグレードをインプレースでキャンセルするには、次の操作を行います。

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
      
      1.  Recreate the `pglogical` subscription on the destination or
        replica by providing the following connection information to the
        AlloyDB primary instance:
      
        ```sql
        SELECT pglogical.create_subscription(
        subscription_name :='test_sub',<br>
        provider_dsn := 'host=primary-ip port=5432 dbname=postgres user=replication_user password=replicapassword'
        );
        ```
      
      1.  Check the status of the subscription by using the following command:
      
        ```sql
        SELECT * FROM pglogical.show_subscription_status('test_sub');
        ```
      
      1.  Test the replication by performing write transactions and
        verifying that the changes are visible on the destination.
      

2. データベースの統計情報を更新します。

   アップグレードが完了したら、プライマリ クラスタで ANALYZE を実行してシステム統計情報を更新します。正確な統計情報があれば、PostgreSQL のクエリ プランナーが最適なクエリ処理を行うことができます。統計情報がないと、クエリプランが不正確になり、パフォーマンスが低下してメモリが過剰に消費される可能性があります。

3. 受け入れテストを実行して、アップグレード後のシステムが想定どおり動作することを確認します。

4. インプレースでアップグレードされたデータベースのメジャー バージョンが、Google Cloud コンソールのクラスタの [概要] ページに表示されていることを確認します。

以前のメジャー バージョンに戻す

アップグレードしたデータベース システムが期待どおりに機能しない場合は、アップグレード前の状態に戻す必要があります。これを行うには、アップグレード前のバックアップ（AlloyDB がアップグレード プロセス中に自動的に作成するバックアップか、既存のアップグレード前のバックアップ）から復元して、アップグレード前の状態の新しいクラスタを作成します。

アップグレード前の状態に復元するには、次の操作を行います。

1. 復元元のアップグレード前のバックアップを特定します。アップグレード プロセス中に、AlloyDB は接頭辞 pre-upgrade-bkp を付けてアップグレード前のバックアップを自動的に作成します。詳細については、バックアップのリストを表示するをご覧ください。

2. アップグレード前のバックアップからの復元を開始します。これにより、以前の PostgreSQL バージョンの新しいクラスタが作成されます。詳細については、保存されたバックアップからクラスタを復元するをご覧ください。

3. アプリケーションを接続します。復元されたクラスタとその読み取りレプリカの詳細でアプリケーションを更新します。復元したクラスタでトラフィックの処理を再開できます。

アップグレード前の時点にポイントインタイム リカバリを実行することもできます。詳細については、ポイントインタイム リカバリ（PITR）を使用するをご覧ください。

制限事項

AlloyDB のメジャー バージョンのインプレース アップグレードには、次の制限が影響します。

• セカンダリ クラスタでは、メジャー バージョンのインプレース アップグレードを実行できません。
• 1,000 を超えるデータベースを持つインスタンスをあるバージョンから別のバージョンにアップグレードするには、長い時間がかかり、アップグレードがタイムアウトする可能性があります。
• AlloyDB は、pg_largeobject_metadata を使用するクラスタのアップグレードをサポートしていません。select count(*) from pg_largeobject_metadata; がゼロ以外の場合、アップグレードは失敗します。
• 特に、スキーマ オブジェクトが少ない大規模なデータベースの場合、メジャー バージョンのインプレース アップグレード オペレーションは、アップグレード前のバックアップまたはアップグレード後のバックアップが完了する前に完了することがあります。
• アップグレードされたインスタンスで書き込みが再開されてから、アップグレード後のバックアップが作成されるまでに、短い遅延が生じることがあります。このため、アップグレード後のバックアップの内容は、メジャー バージョンのアップグレード前のデータベースの内容と一致しない可能性があります。
• メジャー バージョンのインプレース アップグレードが失敗した場合でも、アップグレード前のバックアップが作成されることがあります。
• 自動アップグレードのバックアップは継続的であるため、継続的なバックアップと復元の最大保持期間に達するまで削除できません。最大保持期間に達すると、バックアップはガベージ コレクションされます。また、gcloud CLI を使用してバックアップを手動で削除することもできます。詳細については、バックアップの削除に関する制限事項をご覧ください。

次のステップ

• データベースのメジャー バージョンのインプレース アップグレードについて学習する。
• メジャー バージョンのインプレース アップグレードのトラブルシューティングを行う。
• データベースのメジャー バージョンのインプレース アップグレード エラーについて学習する。