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

このページでは、データを移行するのではなく、Cloud SQL インスタンスをインプレース アップグレードでデータベースのメジャー バージョンのアップグレードを行う方法について説明します。

はじめに

データベース ソフトウェア プロバイダは、新機能、パフォーマンス改善、セキュリティ強化を含む新しいメジャー バージョンを定期的にリリースしています。Cloud SQL では、新しいバージョンがリリース後に取り込まれます。Cloud SQL で新しいメジャー バージョンのサポートが提供された後、インスタンスをアップグレードして、データベースを最新の状態に保つことができます。

インスタンスのデータベース バージョンをアップグレードするには、インプレース アップグレードまたはデータの移行を行います。インプレース アップグレードは、インスタンスのメジャー バージョンをアップグレードするためのより簡単な方法です。データの移行や、アプリケーション接続文字列の変更は必要ありません。インプレース アップグレードを使用すると、アップグレード後も、現在のインスタンスの名前、IP アドレス、その他の設定を維持できます。インプレース アップグレードは、データファイルを移動する必要がないため、より短時間で完了できます。場合によっては、データの移行よりもダウンタイムが短くなります。

メジャー バージョン アップグレードの計画

1. 対象のメジャー バージョンを選択します。

   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 メソッドと URL:

   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 メソッドと URL:

   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 がサポートしているデータベース バージョンの一覧については、データベースのバージョンとバージョン ポリシーをご覧ください。

2. データベースの各メジャー バージョンで提供される機能を検討し、非互換性の問題を解決します。

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

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

3. ドライランでアップグレードをテストします。

   本番環境データベースをアップグレードする前に、テスト環境でエンドツーエンドのアップグレード プロセスのドライランを実行します。インスタンスのクローンを作成して、アップグレード プロセスのテストに使用するデータをコピーします。

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

4. アップグレードのタイミングを決定します。

   アップグレード中は、インスタンスが一定期間使用できなくなります。データベース アクティビティが低い時間帯にアップグレードを行うように計画してください。

メジャー バージョン アップグレードを準備する

アップグレードを行う前に、次の手順を行います。

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. リードレプリカを管理します。

   Cloud SQL for PostgreSQL はクロス バージョン レプリケーションをサポートしていません。つまり、インスタンスがリードレプリカに複製している間は、プライマリ インスタンスをアップグレードできません。アップグレードを行う前に、リードレプリカごとにレプリケーションを無効にするか、リードレプリカを削除します。

3. Cloud SQL が論理レプリケーションのソースの場合は、次のように pglogical 拡張レプリケーションを無効にします。これは、アップグレード後に再度有効にできます。Cloud SQL が論理レプリケーションのターゲットの場合、これらの手順を行う必要はありません。
   1. 次のコマンドを使用して、サブスクリプションを無効にし、プロバイダからレプリカの接続を解除します。

      SELECT * FROM pglogical.alter_subscription_disable(subscription_name name, immediate bool);

      name を、既存のサブスクリプションの名前に置き換えます。

      サブスクリプションをすぐに無効にする場合は、immediate パラメータの値を true に設定します。デフォルト値は false です。サブスクリプションは、現在のトランザクションが終了した後に無効になります。

      次に例を示します。

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

   2. パブリッシャーまたは Cloud SQL プライマリ インスタンスに接続して次のコマンドを実行し、レプリケーション スロットを削除します。

      SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots
        WHERE slot_name IN (SELECT slot_name FROM pg_replication_slots);

      次に例を示します。

      postgres=> SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots
      postgres->    WHERE slot_name IN (SELECT slot_name FROM pg_replication_slots);
      -[ RECORD 1 ]------------+-
      pg_drop_replication_slot |
      
      postgres=>

4. 残りの 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 インスタンスのバージョンの確認をご覧ください。
5. カスタム データベース フラグを管理します。PostgreSQL インスタンスに構成したカスタム データベース フラグの名前を確認します。これらのフラグに関連する問題については、PostgreSQL インスタンスのカスタムフラグの確認をご覧ください。
6. あるメジャー バージョンから別のメジャー バージョンへのアップグレードを行う場合は、各データベースに接続して、互換性の問題があるかどうかを確認します。データベースが相互に接続できることを確認します。各データベースの datallowconn フィールドを確認して、接続が許可されていることを確認します。t 値は許可されていることを意味し、f 値は接続を確立できないことを示します。
7. Datadog インストールを使用して Cloud SQL インスタンスを PostgreSQL 10 以降のバージョンにアップグレードする場合は、アップグレード前に pg_stat_activity() 関数を削除します。

既知の制限事項

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

• 外部レプリカでは、メジャー バージョンのインプレース アップグレードを実行できません。
• 1,000 を超えるデータベースを持つインスタンスをあるバージョンから別のバージョンにアップグレードするには、長い時間がかかり、タイム・アウトする可能性があります。
• select * from pg_largeobject_metadata; ステートメントを使用して、Cloud SQL インスタンスの各 PostgreSQL データベース内の大規模オブジェクトの数をクエリします。すべてのデータベースの結果が 1, 000 万件を超える大規模なオブジェクトである場合、アップグレードは失敗します。Cloud SQL はデータベースを以前のバージョンにロールバックします。
• PostgreSQL 16 以降へのインプレース メジャー バージョン アップグレードを実行する前に、すべてのデータベースの PostGIS 拡張機能をバージョン 3.4.0 にアップグレードします。
• PostgreSQL バージョン 9.6、10、11、または 12 を使用している場合、PostGIS 拡張機能のバージョン 3.4.0 はサポートされていません。したがって、PostgreSQL 16 以降へのインプレース メジャー バージョン アップグレードを実行するには、まず PostgreSQL の中間バージョン（バージョン 13、14、15）にアップグレードする必要があります。

• インスタンスに pgRouting 拡張機能と pg_squeeze 拡張機能をインストールした場合、メジャー バージョンのアップグレードは実行できません。この問題を解決するには、これらの拡張機能をアンインストールしてからアップグレードを実行してください。拡張機能の詳細については、PostgreSQL 拡張機能を構成するをご覧ください。

• vacuum_defer_cleanup_age フラグと force_parallel_mode フラグを有効にすると、メジャー バージョンのアップグレードを実行できません。この問題を解決するには、これらのフラグを削除してからアップグレードを実行します。フラグの詳細（削除方法など）については、データベース フラグを構成するをご覧ください。

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

アップグレード操作を開始すると、Cloud SQL は、最初にインスタンスの構成をチェックしてアップグレードの互換性を確認します。構成を確認すると、Cloud SQL は、インスタンスを利用不可にして、アップグレード前のバックアップを作成します。その後、アップグレードを実行し、インスタンスを使用可能にして、アップグレード後のバックアップを作成します。

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 は 2 つのオンデマンド バックアップ（アップグレード バックアップと呼ばれます）を自動的に作成します。

• 最初のアップグレード バックアップは、アップグレード前のバックアップで、アップグレードの直前に作成されます。このバックアップは、データベース インスタンスを以前のバージョンの状態に復元するために使用できます。
• 2 番目のアップグレード バックアップは、アップグレード後のバックアップで、アップグレードされたデータベース インスタンスへの新しい書き込みが許可された直後に作成されます。

バックアップのリストを表示すると、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. アップグレード前にインスタンスで 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. Cloud SQL プライマリ インスタンスに次のように接続の詳細を提供し、移行先（レプリカ）で pglogical サブスクリプションを再作成します。

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

      次に例を示します。

      postgres=> SELECT pglogical.create_subscription(
      postgres(>     subscription_name := 'test_sub',
      postgres(>     provider_dsn := 'host=10.58.64.90 port=5432 dbname=postgres user=postgres password=postgres'
      postgres(> );
      -[ RECORD 1 ]-------+-----------
      create_subscription | 2769129391

   3. 次のコマンドを使用して、サブスクリプションのステータスを確認します。

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

   4. 書き込みトランザクションを実行し、変更が宛先で表示されることを確認して、レプリケーションをテストします。

2. リードレプリカをアップグレードします。

   リードレプリカのレプリケーションを停止した場合は、これらを個別にアップグレードします。プライマリ インスタンスのアップグレードに使用した任意の方法を使用できます。レプリカをアップグレードすると、Cloud SQL は IP アドレスを保持したままレプリカを再作成します。プライマリの最新のデータで更新し、レプリカを再起動します。

   プライマリ インスタンスをアップグレードする前にリードレプリカを削除した場合は、新しいリードレプリカを作成できます。これは、アップグレードされたデータベース バージョンに自動的にプロビジョニングされます。

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

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

4. 承認テストを実行します。

   アップグレード後のシステムが想定どおり動作することを確認するために、テストを実施する必要があります。

メジャー バージョン アップグレードのトラブルシューティング

無効なアップグレード コマンド（インスタンスに新しいバージョンの無効なデータベース フラグが含まれている場合など）を試行すると、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 のエラーログを表示] リンクをクリックします。

   [ログ エクスプローラ] ページが開きます。

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 フラグの値をインスタンス内のテーブルの約 2 倍に設定します。このフラグの値を変更すると、インスタンスは再起動されます。

接続容量を確認する

インスタンスの接続容量が不足している場合は、「ERROR: Insufficient connections.」というエラー メッセージが表示されることがあります。

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 がアップグレードを実行する間、インスタンスは一定期間使用できません。

アップグレードにはどれくらい時間がかかりますか？

通常、1 つのインスタンスのアップグレードには 10 分もかかりません。インスタンス構成で使用されている vCPU またはメモリが少ない場合、アップグレードに時間がかかることがあります。

インスタンスでホストされているデータベースやテーブルが多すぎる場合や、データベースが非常に大きい場合は、アップグレードに数時間がかかったりタイムアウトになることがあります。これは、アップグレード時間がデータベース内のオブジェクト数と対応するためです。アップグレードが必要なインスタンスが複数ある場合は、それに比例してアップグレードの合計時間が長くなります。

アップグレード プロセスの各ステップをモニタリングできますか？

Cloud SQL ではアップグレード オペレーションが進行中かどうかをモニタリングできますが、アップグレードの個々のステップを追跡することはできません。

開始後にアップグレードをキャンセルできますか？

いいえ、アップグレードを開始すると、キャンセルはできません。アップグレードに失敗すると、Cloud SQL は以前のバージョンのインスタンスを自動的に復元します。

アップグレード中に設定はどうなりますか？

インプレースのメジャー バージョン アップグレードを実行すると、Cloud SQL はインスタンス名、IP アドレス、明示的に構成されたフラグ値、ユーザーデータなどのデータベース設定を保持します。ただし、システム変数のデフォルト値は変更されることがあります。たとえば、PostgreSQL 13 以前の password_encryption フラグのデフォルト値は md5 です。PostgreSQL 14 にアップグレードすると、このフラグのデフォルト値は scram-sha-256 に変更されます。

詳細については、データベース フラグを構成するをご覧ください。特定のフラグまたは値がターゲット バージョンでサポートされなくなった場合、Cloud SQL はアップグレード中にフラグを自動的に削除します。

次のステップ

• インスタンスへの接続オプションについて学習します。
• データのインポートとエクスポートについて学習する。
• データベース フラグの設定について学ぶ