最終更新日 2025年05月28日(水)

Heroku では、Heroku Postgres アドオンのための Postgres メジャーバージョンのアップグレードをテストしてから、本番データベースでアップグレードを実行する​ことをお勧めします。

バージョンアップグレードをテストすることは、データベースまたはアプリケーションに影響を及ぼす可能性がある、考えられるすべてのアップグレードエラーや非互換性の問題を特定するのに役立ちます。テストを行うと、本番データベースをアップグレードするときにアプリケーションのダウンタイムを削減するのに役立ちます。

アップグレードの最も一般的な問題は、Postgres バージョン間の型の非互換性やオブジェクトの参照または依存関係のエラーのほか、アプリまたはその PostgreSQL ドライバーのバージョンがターゲットの Postgres バージョンをサポートしない場合の一般的なアプリケーションの問題に関するものです。

バージョンアップグレードをテストする方法は 3 つあります。

• pg:upgrade:dryrun​ の使用 (Standard 層以上のリーダーデータベースに推奨)
• フォークしたデータベースの使用
• pg:copy​ の使用

pg:upgrade:dryrun を使用したテスト

Heroku Postgres のすべてのバージョンアップグレードには upgrade コマンド​を使用することをお勧めしますが、アップグレードをテストできるのは Standard 層以上の pg:upgrade:dryrun​ リーダーデータベースのみです。Essential 層のデータベースの場合は、pg:copy を使用してテストします。フォロワーデータベースの場合は、フォークしたデータベース​または pg:copy を使用してテストします。

pg:upgrade:dryrun コマンドは、フォロワーデータベースを作成してアップグレードすることによってバージョンアップグレードをシミュレートします。Heroku はテストアップグレードの結果をメールで送信します。テストアップグレードが終了すると、すぐにフォロワーのプロビジョニングが解除されます。

$ heroku pg:upgrade:dryrun HEROKU_POSTGRESQL_RED --app example-app
› Warning: Destructive action.
› This command starts a test upgrade for HEROKU_POSTGRESQL_RED to Postgres version 17.
›
› You can't undo this action.

To proceed, type example-app or re-run this command with --confirm example-app: example-app
Starting a test upgrade on postgresql-curly-52280... done
›   Started test upgrade. We'll notify you via email when it's complete.

テスト後、pg:upgrade:prepare を使用してリーダーデータベースのバージョンアップグレードを開始できます。

フォークしたデータベースでのテスト

フォークしたデータベースのメソッドを使用すると、アップグレードしたデータベースをアプリでテストできます。この方法は、フォロワーデータベース​でアップグレードをテストする場合にお勧めです。

まず、ステージングアプリまたは非本番アプリ上で既存の本番データベースをフォークし​、完全なアップグレードプロセスを実行して検証します。

$ heroku addons:create heroku-postgresql:​<database_plan> --fork production_app_name::DATABASE_URL --as PROD_DB_FORK -a staging_app_name

$ heroku addons:create heroku-postgresql:<database_plan> --as PROD_DB_FORK -a staging_app_name -- --fork production_app_name::DATABASE_URL

フォークしたデータベースの準備ができたら、フォロワーデータベースでバージョンアップグレードプロセス​を開始し、そのフォロワーを作成します。

$ heroku addons:create heroku-postgresql:​<database_plan> --follow staging_app_name::PROD_DB_FORK --as TEST_UPGRADE_FOLLOWER --app staging_app_name

$ heroku addons:create heroku-postgresql:<database_plan> --as TEST_UPGRADE_FOLLOWER --app staging_app_name -- --follow staging_app_name::PROD_DB_FORK staging_app_name

テストフォロワーをアップグレードするには、この記事の手順に従います。データベースのバージョンアップグレードテストを実行するには、アップグレードされたデータベースを、非本番アプリケーションのプライマリデータベースとしてプロモートします。アプリケーションが期待どおりにデータベースと接続して通信できることを確認します。

$ heroku pg:promote TEST_UPGRADE_FOLLOWER --app staging_app_name

このアプローチにより、ユーザーは完全なアップグレードプロセスをテストし、本番環境でアップグレードするときにアップグレードの所要時間を見積もることができます。このプロセスは、(アプリケーションで古い PostgreSQL クライアントやドライバーを使用しない場合に) アプリケーションが新しい PG バージョンと互換性があることを確認するためにも役立ちます。

アップグレードのテストが完了したら、フォークされたデータベース​とアップグレードされたフォロワーを削除できます。

もう 1 つのテストアプローチ

バージョンアップグレードのテストプロセスをスピードアップするために、別のアプローチとして、非本番環境に本番アプリケーションのフォロワーを作成する方法があります。pg:upgrade:run​をフォロワーで直接実行できます。

アップグレードされたデータベースを非本番環境内でプライマリデータベースとしてプロモートし、アプリケーションに新しいバージョンとの互換性があることを確認します。

pg:copy を使用したテスト

pg:copy​ のメソッドを使用して、10 GB 以下の Postgres バージョンのデータベースをアップグレードします。pg:copy​ を使用すると、すべての Heroku Postgres プランでバージョンアップグレードをテストできます。

フォークしたデータベースのメソッドを使用すると、アップグレードしたデータベースをアプリでテストできます。この方法は、フォロワーデータベースでアップグレードをテストする場合にお勧めです。

アップグレードプロセスをテストするには、非本番アプリケーション上に新しいデータベースをプロビジョニングし、ターゲットの Postgres バージョンを指定します。

$ heroku addons:create heroku-postgresql:​<database_plan> --version=15 --as DATABASE_UPGRADE_TEST --app staging_app_name

$ heroku addons:create heroku-postgresql:<database_plan> --as DATABASE_UPGRADE_TEST --app staging_app_name -- --version=15

新しいデータベースが使用可能になったため、データを本番データベースから新しいデータベースにコピーします。

$ heroku pg:copy production_app_name::DATABASE_URL DATABASE_UPGRADE_TEST --app staging_app_name

データコピーが完了した後、データベースを非本番アプリケーションにプロモートし、アプリケーションが新しいバージョンと互換性があることを確認します。

$ heroku pg:promote DATABASE_UPGRADE_TEST --app staging_app_name