G-gen の今村です。Cloud SQL for PostgreSQL を、インプレースアップグレードという方法でメジャーバージョンアップする手順を解説します。当記事では、バージョン17からバージョン18へのアップグレードを例とします。

概要

インプレースアップグレードについて

Cloud SQL for PostgreSQL におけるメジャーバージョンアップには、従来から用いられているダンプ＆リストアによるデータ移行方式と、インプレースアップグレード方式があります。

インプレースアップグレード方式は、既存のインスタンスをそのまま新しいバージョンにアップグレードする機能です。この方式には以下のようなメリットがあります。

データのエクスポート・インポートが不要なため、作業時間を大幅に短縮できる
IP アドレスが変更されないため、アプリケーション側の接続設定の変更が不要
アップグレード前に自動でバックアップが取得されるため、安全性が高い

なお、Cloud SQL では PostgreSQL のほかに MySQL や SQL Server でもインプレースアップグレード機能がサポートされています。ただし、データベースエンジンごとに事前チェックのエラー内容や、アップグレード完了後の仕上げ作業の仕様が異なります。そのため、当記事では Cloud SQL for PostgreSQL に特化して手順を解説します。

Cloud SQL の概要については、以下の記事を参照してください。

blog.g-gen.co.jp

参考 : データベースのメジャーバージョンのインプレースアップグレード

手順の概要

インプレースアップグレードは非常に強力な機能ですが、本番環境でいきなり実行することは推奨されません。安全にアップグレードを完了させるため、以下のようなロードマップで作業を進めます。

本番インスタンスのクローン作成（検証環境の準備）
クローン環境での事前チェックの実行
クローン環境でのアップグレード実行
クローン環境での仕上げ作業とアプリケーションの動作検証
本番環境での事前チェックとアップグレード実行
本番環境での仕上げ作業（ANALYZE）と最終動作検証

事前準備

クローンインスタンスの作成

本番稼働に影響を与えないよう、[クローンを作成] から検証用インスタンスを作成します。まずは、このクローンインスタンスを対象にすべてのアップグレード工程を検証します。

十分なディスク容量の確認

メジャーバージョンアップを実行する前に、十分なディスク容量が確保されていることを必ず確認してください。特にストレージの自動増量機能を有効にしていない場合は、注意が必要です。

クローンインスタンスでテストアップグレードを実行する前後でストレージ容量をメモしておくことで、実際に使用されるストレージ容量を把握できます。これに基づいて、本番環境のアップグレード前に容量を拡張すべきかどうかを判断してください。

事前チェック

概要

Cloud SQL には、アップグレードが成功するかどうかを事前に検証できる事前チェック機能が備わっています。クローンインスタンスに対してこの機能を実行することで、本番稼働に影響を与えることなく、データベースの設定や拡張機能の非互換性などの問題の洗い出しができます。

事前チェックでエラーや警告が出た場合は、アップグレードが失敗する可能性が高いため、必ず原因を特定して対処する必要があります。

チェックの実行

事前チェックはgcloudコマンドで実行します。以下のコマンドを実行することで、対象のインスタンスが PostgreSQL 18にアップグレード可能かを確認できます。

INSTANCE_NAME（クローンインスタンス名）、PROJECT_ID（プロジェクト ID）、TARGET_DATABASE_VERSION（今回はPOSTGRES_18）を、それぞれ置き換えて実行してください。

gcloud sql instances pre-check-major-version-upgrade INSTANCE_NAME \
    --project=PROJECT_ID \
    --target-database-version=TARGET_DATABASE_VERSION

参考 : データベースのメジャーバージョンをインプレースでアップグレードする - 事前チェックを実行する

結果の確認

gcloudコマンドを実行して特にエラーが出ずに完了した場合、以下のようなメッセージが表示されます。

赤枠で囲まれている主要な文言の意味は以下のとおりです。

No issues or warnings detected during pre-check.

事前チェックにおいて、アップグレードの妨げとなるエラーや警告が検出されなかったことを意味します。このメッセージが表示された場合は、対象のインスタンスが新しいデータベースバージョンへアップグレードできる状態であると判断できます。

PreCheckResults: [ ]

検出された問題の詳細が出力されるエリアです。エラーや警告が存在しない場合は、空の配列（[]）として表示されます。互換性のない拡張機能などの問題がある場合は、この中に具体的なエラー要因が出力されます。

Status: COMPLETED

事前チェックのプロセスが正常に完了したことを示します。

エラー詳細の確認

コマンドの出力結果にエラーが含まれている場合は、Cloud Logging のログエクスプローラから詳細なエラー内容を確認します。

Cloud Logging の概要や仕組みについては、以下の記事を参照してください。

blog.g-gen.co.jp

よくある事前チェックエラーと対策

拡張機能の互換性

データベースのメジャーバージョンをアップグレードしても、機能拡張はそのまま動作するケースが多いです。

ただし一部の拡張機能は、新しい PostgreSQL バージョンと互換性のあるバージョンに事前にアップデートしておく必要があります。拡張機能のバージョンが古いと、アップグレードがブロックされる可能性があります。

テンプレートデータベースの文字セット

templateなどのテンプレートデータベースの文字セットや照合順序を確認します。これらの形式が新しいバージョンでサポートされていない場合、アップグレードは失敗します。

文字セットをen_US.UTF8に変更するなど、事前に適切な設定に変更してください。

参考 : データベースのメジャーバージョンをインプレースでアップグレードする - メジャーバージョンアップグレードを準備する

インプレースアップグレードの実行

コンソールからの実行

事前チェックをクリアしたら、まずはクローンインスタンスを対象に実際のアップグレードを実行します。なお、リードレプリカが存在する場合は、プライマリインスタンスをアップグレードするとレプリカも自動的にアップグレードされます。

Google Cloud コンソールから実行する場合は、インスタンスの詳細画面から [編集] をクリックし、次の手順に従ってアップグレードを進めます。

gcloud コマンドからの実行

一方で、Google Cloud コンソールではなく gcloudコマンドを使用してアップグレードする場合は、以下のコマンドを実行します。INSTANCE_NAME（クローンインスタンス名）、DATABASE_VERSION（今回はPOSTGRES_18）を、それぞれ置き換えて実行してください。

gcloud sql instances patch INSTANCE_NAME \
    --database-version=DATABASE_VERSION

コマンドからのアップグレードに時間を要する場合、以下のようなタイムアウトのエラーが起きる場合があります。

この表示はアップグレードの失敗を意味するものではありません。Google Cloud 側での処理はバックグラウンドで継続していますが、手元のgcloudコマンドの待ち時間を超えたために、一旦コマンドの同期処理が終了した状態です。

アップグレードが完了したかどうかを確認するには、ログに表示されている以下のコマンドをそのまま実行します。

gcloud beta sql operations wait --project PROJECT_ID OPERATION_ID

このコマンドを実行することで、再びバックグラウンドの処理を追跡できるようになります。Cloud SQL のアップグレードはデータ量によって数十分以上の時間がかかるケースもあるため、このコマンドを使用して進捗を確認します。

参考 : データベースのメジャーバージョンをインプレースでアップグレードする - 単一インスタンスのメジャーバージョンをアップグレードする

アップグレードの確認

コンソールからは、インスタンスの詳細画面で確認できます。

コンソールに出力された前述のコマンドを実行して、コマンドベースでの確認も可能です。

クローン環境での仕上げ作業と動作検証

システム統計情報の更新

アップグレード完了後、必ず実行すべき作業の1つがシステム統計情報の更新です。データベースに対してANALYZEコマンドを実行し、クエリプランナーが最適な実行計画を立てられるようにします。これを行わないと、クエリのパフォーマンスが著しく低下する可能性があります。

ANALYZE VERBOSE;

システム統計情報の更新は、アプリケーションが実際に使っているデータベースに接続して、それぞれ実行する必要があります。

接続テストと動作検証

アップグレードプロセスでは、アップグレード前（Pre-upgrade）のバックアップと、アップグレード後（Post-upgrade）のバックアップが自動的に作成されます。バックアップ一覧画面から、これらのバックアップが正常に取得されていることを確認します。いつでも元に戻せる状態であることを確認した上で、アプリケーションからの接続テストや動作検証を十分に実施してください。