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

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

このページでは、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; がゼロ以外の場合、アップグレードは失敗します。
• 特に、スキーマ オブジェクトが少ない大規模なデータベースの場合、インプレース メジャー バージョン アップグレード オペレーションは、アップグレード前のバックアップまたはアップグレード後のバックアップの完了前に完了することがあります。
• アップグレードされたインスタンスで書き込みが再開されてから、アップグレード後のバックアップが作成されるまでに、短い遅延が生じることがあります。つまり、アップグレード後のバックアップの内容は、メジャー バージョンのアップグレード前の DB の内容と一致しない可能性があります。
• インプレース メジャー バージョン アップグレードが失敗した場合でも、アップグレード前のバックアップが作成されることがあります。
• 自動アップグレード バックアップは継続的であるため、継続的なバックアップと復元の最大保持期間に達するまで削除できません。最大保持期間に達すると、バックアップはガベージ コレクションされます。または、gcloud CLI を使用してバックアップを手動で削除することもできます。詳細については、バックアップの削除に関する制限事項をご覧ください。

次のステップ

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