最終更新日 2025年06月17日(火)

この記事では、Heroku Postgres データベースのメジャー Postgres バージョンをアップグレードする方法について説明します。Heroku でサポートされている最新のメジャー Postgres バージョンは 17 です。

メジャー Postgres バージョンは Heroku CLI 経由でのみアップグレードできます。これは、慎重に実行する必要のある重大な操作です。

Heroku では、データベースの Postgres バージョンをアップグレードするための 3 つの方法がサポートされています。どの方法でも、アップグレード中のデータ損失を防ぐために、ある程度のアプリケーションのダウンタイムが必要になります。

pg:upgrade:* コマンドでのアップグレード

pg:upgrade:*​ コマンド​を使用してEssential 層のデータベース、Standard 層以上のデータベース、およびフォロワーデータベースのバージョンアップグレードを実行することができます。

アップグレードコマンドは、PostgreSQL の ​pg_upgrade ユーティリティ​を使用して PostgreSQL バージョンをその場でアップグレードします。これらのコマンドを使用してバージョンのアップグレードを実行するには、多くの場合、約 5 ～ 10 分のアプリのダウンタイムが必要になります。

Essential 層およびフォロワー

この方法は全 Essential 層​の Heroku Postgres プランおよびフォロワーデータベース​でサポートされています。フォロワーデータベースでこの方法を使用すると、フォロワーの Postgres バージョンをアップグレードする前に、リーダーデータベースのフォローが解除されます。

バージョンをアップグレードするには、次のデータベースで直接 pg:upgrade:run​ を実行します。

$ heroku pg:upgrade:run HEROKU_POSTGRESQL_RED --app example-app

Standard 層およびそれ以上

アップグレードコマンドを使用してデータベースバージョンをアップグレードするには、次の手順を実行します。

1. pg:upgrade:prepare​ を実行して、リーダーデータベースのアップグレード準備を整え、次の利用可能なメンテナンスウィンドウ​中にアップグレードをスケジュールします。
2. スケジュール済みのアップグレードのメンテナンスまで待つか、リーダーデータベースで pg:upgrade:run​ を実行して、準備されたアップグレードを開始します。

pg:upgrade:dryrun​ コマンドを使用して、事前にバージョンアップグレードをテスト​できます。

1. バージョンアップグレードの準備をする

はじめに、リーダーデータベースで pg:upgrade:prepare​ を実行します。

$ heroku pg:upgrade:prepare HEROKU_POSTGRESQL_RED --app example-app

このコマンドはアップグレードを準備し、次に利用可能なメンテナンスウィンドウ​にアップグレードのスケジュールを設定します。アップグレードの準備が整い、スケジュールが設定されると、メール通知が届きます。アップグレードの状況は pg:upgrade:wait または pg:info を使用して確認できます。たとえば、pg:upgrade:wait​ を使用します。

$ heroku pg:upgrade:wait HEROKU_POSTGRESQL_RED --app example-app
Waiting for database postgresql-crystalline-69217... ⣟ preparing service for upgrade

スケジュール済みのメンテナンスが始まる前、またはアップグレードを開始する前に、pg:upgrade:cancel を使用して、準備されたアップグレードをキャンセルすることができます。

2. バージョンアップグレードを実行する

アップグレードの準備とスケジュール設定が完了したら、メンテナンスウィンドウまで待ってアップグレードが自動的に開始されるのを待つか、次のコマンドを使用して、リーダーデータベースでバージョンアップグレードを手動で開始することができます。

$ heroku pg:upgrade:run HEROKU_POSTGRESQL_RED --app example-app

アップグレードを開始した後はキャンセルできません。このコマンドは、接続されているフォロワーデータベースもアップグレードします。すべてのフォロワーをアップグレードするには、ある程度の時間がかかります。

アップグレードの状況は pg:upgrade:wait​ を使用して確認できます。

$ heroku pg:upgrade:wait HEROKU_POSTGRESQL_RED --app example-app
Waiting for database postgresql-crystalline-69217... ⣟ (1/8) checking upgrade service

フォロワーデータベースでのアップグレード

フォロワーデータベースでバージョンアップグレードを実行するには、データベースのフォロワー​をアップグレードし、それを新しいアップグレードされたデータベースとして昇格させます。この方法では、別のアドオンでアップグレードを実行するため、アップグレード後も古いデータベースは引き続き使用できます。フォロワーデータベースでアップグレードを実行するには、約 30 分のアプリのダウンタイムが必要になります。

Postgres バージョンおよびプランの両方をアップグレードする必要がある場合は、別のプランで新しいフォロワーをプロビジョニングし、切り替えプロセス​の一部として pg:upgrade:run​ を使用します。

この方法を使用すると、フォークされたデータベースで事前にバージョンアップグレードをテスト​できます。

1. フォロワーデータベースをプロビジョニングする

開始するには、データベースのフォロワーを作成​し、そのフォロワーがリーダーデータベースに追いつくまで待ちます。この例では、standard-2​ プランのフォロワーが HEROKU_POSTGRESQL_LAVENDER_URL​ に作成されます。ニーズに最適なプラン​をプロビジョニングできます。HEROKU_POSTGRESQL_LAVENDER_URL​は、アップグレードしようとしているデータベースの環境設定​に置き換えてください。

$ heroku addons:create heroku-postgresql:standard-2 --follow HEROKU_POSTGRESQL_LAVENDER_URL --app example-app

$ heroku addons:create heroku-postgresql:standard-2 --app example-app -- --follow HEROKU_POSTGRESQL_LAVENDER_URL
Adding heroku-postgresql:standard-2 to example-app... done, v71 ($200/mo)
Attached as HEROKU_POSTGRESQL_WHITE
Follower will become available for read-only queries when up-to-date
Use `heroku pg:wait` to track status

$ heroku pg:wait
Waiting for database HEROKU_POSTGRESQL_WHITE_URL... performing final cleanup steps after upgrade

フォロワーは、プライマリデータベースまで 200 コミット以内のときに「追いついた」と見なされます。フォロワーのコミット数がどのくらい遅れているかは、pg:info​ コマンドを使用して確認できます(フォロワーデータベースの Behind By​ 行を参照)。

$ heroku pg:info --app example-app
=== HEROKU_POSTGRESQL_LAVENDER
Plan:        Standard 0
Status:      available
...
=== HEROKU_POSTGRESQL_WHITE
Plan:        Standard 2
Status:      available
...
Following:   HEROKU_POSTGRESQL_LAVENDER (DATABASE_URL)
Behind By:   125 commits

2. データベースの書き込みを防止するためにメンテナンスモードにする

アップグレードプロセス中に、新しいデータは新しいデータベースに転送されないため、現在のプライマリデータベースに新しいデータが書き込まれないようにすることが重要です。これを行うには、アプリをメンテナンスモード​にします。スケジューラージョブも実行されている場合は、これを無効にします。メンテナンスモードの間、データベースでは請求時間が発生し続けます。

$ heroku maintenance:on --app example-app
Enabling maintenance mode for example-app... done

3. フォロワーデータベースをアップグレードする

メンテナンスモードになり、プライマリデータベースに追加データが書き込まれていない状態になったので、フォロワーデータベースをアップグレードできます。

フォロワーデータベースがプライマリに完全に追いつくまで (遅れが 0 commits​ と表示されるまで) 待ちます。

$ heroku pg:info --app example-app
=== HEROKU_POSTGRESQL_LAVENDER_URL
Plan:        Standard 0
Status:      available
...
=== HEROKU_POSTGRESQL_WHITE_URL
Plan:        Standard 2
Status:      available
...
Following:   HEROKU_POSTGRESQL_LAVENDER_URL (DATABASE_URL)
Behind By:   0 commits

フォロワーが追いつくまで待たないと、次のエラーメッセージが表示されることがあります。

 ▸    database is too far behind its leader. Wait until your follower catches up with its leader and try again.

フォロワーが追いついたら、pg:upgrade:run​ コマンドを使用して、フォロワーの Postgres バージョンをその場でアップグレードします。アップグレードにより、フォロワーはプライマリデータベースのフォロー解除も行います。この手順は通常、完了するまでに約 20 分かかります。

$ heroku pg:upgrade:run HEROKU_POSTGRESQL_WHITE --app example-app

pg:upgrade:wait​ または pg:wait​ を使用して、アップグレードの進捗状況を監視できます。

$ heroku pg:upgrade:wait --app example-app
Waiting for database HEROKU_POSTGRESQL_WHITE_URL... performing final cleanup steps after upgrade

pg:upgrade:run​ プロセスの一部として、Heroku Postgres はデータベースに対して ANALYZE​を実行します。このプロセスにより、データベースの統計が再計算され、バージョンアップグレードの後も Postgres クエリプランナーに確実に最新情報が保持されるようになります。すべての資格情報とカスタム資格情報​も、アップグレードプロセスの一環としてローテーションされます。

pg:upgrade:run​ コマンドは、データベース内のテーブルのデータ型に互換性がないなどのエラーが原因で失敗する可能性があります。アップグレードに失敗した場合は、pg:upgrade:wait​ または pg:wait​ を実行すると、version upgrade error, check your Heroku email notifications for details​ が返されます。エラーを解決した後、アップグレードを再開できます。

4. 新しいデータベースをプロモートまたはアタッチする

DATABASE_URL​ が以前のプライマリデータベースの環境設定​だった場合は、pg:promote​ を使用して新しくアップグレードしたデータベースを新しい DATABASE_URL​ としてプロモートします。pg:promote​ では、新しい HEROKU_POSTGRESQL_<color>_URL​ 環境設定に割り当てられた、古いプライマリデータベースの代替アタッチメントが作成されます。このプロモーションプロセスによってリリースがトリガーされ、アプリが再起動されます。

$ heroku pg:promote HEROKU_POSTGRESQL_WHITE --app example-app
Promoting HEROKU_POSTGRESQL_WHITE_URL to DATABASE_URL... done

アプリはまだ新しいリクエストを受信して​​いませんが、これで手順 1 で作成した​フォロワーデータベースがアプリのプライマリデータベース (DATABASE_URL​) になりました。

アップグレードするデータベースにデフォルトの DATABASE_URL​ とは異なる環境設定がある場合は、heroku addons:attach を使用して、必要なエイリアスまたはアタッチメント名で新しくアップグレードしたデータベースをプロモートします。元のプライマリデータベースが複数のアプリにアタッチされていた場合は、addons:attach​ を使用して新たにアップグレードされたデータベースをこれらのアプリにアタッチする必要があります。

$ heroku addons:create heroku-postgresql:standard-0 -a example-app -- --follow DATABASE_URL

$ heroku addons:create heroku-postgresql:standard-0 --follow DATABASE_URL --app example-app

$ heroku pg:connection-pooling:attach DATABASE_URL --as MY_DATABASE_CONNECTION_POOL -a example-app

5. メンテナンスモードを終了する

通常のアプリケーション操作を再開するには、Web 以外のすべての dyno をその元のレベルにスケーリングします (heroku ps:scale worker=1​ など)。

最後に、メンテナンスモードをオフにします。

$ heroku maintenance:off --app example-app

これで、アップグレードされたデータベースインスタンスへのリクエストをアプリケーションが受信するようになりました。これは、heroku pg:info​ を実行することによって確認できます。DATABASE_URL​ で示されるデータベースはプライマリデータベースと見なされます。

pg:copy でのアップグレード

pg:copy​ のアップグレード方法では、PostgreSQL のネイティブなバックアップと復元ユーティリティを使用します。データベースバックアップをディスクに書き込む代わりに、バックアップデータを新しくプロビジョニングされたデータベースの復元プロセスに直接ストリーミングします。このプロセスによって肥大化 (データベース上の使用されなくなった行によって占有される余分な領域) を減らし、ディスク領域を節約できます。

pg:copy​ の方法では、現在のデータベースの GB あたり約 3 分のアプリのダウンタイムが必要ですが、この量はスキーマやデータベースプランによって大きく異なる場合があります。必要なダウンタイムは、アップグレードをテストする (非本番アプリケーションの新しいデータベース上でアップグレードプロセスを実行する) ことによって見積もることができます。

pg:copy​ の方法では、サポートされているすべての Heroku Postgres プランとバージョン間のアップグレードがサポートされています。pg:copy​ は、デフォルトの資格情報とそれがアクセスできるデータのみをコピーします。その他の資格情報と、それでしかアクセスできないデータはコピーされません。この方法を使用すると、事前にバージョンアップグレードをテスト​することもできます。

1. 新しいデータベースをプロビジョニングする

目的のプランの新しい Heroku Postgres データベースをプロビジョニングします (次の例では、standard-0​ プランが使用されていますが、ニーズに最適なプラン​をプロビジョニングする必要がある)。

$ heroku addons:create heroku-postgresql:standard-0 --app example-app
Adding heroku-postgresql:standard-0 on example-app... done, v122 ($50/mo)
The database should be available in 3-5 minutes

Standard、Premium、および Private 層データベースのプロビジョニングには数分かかります。pg:wait​コマンドを使用すると、プロビジョニングがいつ完了したかの通知を受け取ることができます。

$ heroku pg:wait -a example-app
Waiting for database HEROKU_POSTGRESQL_PINK_URL... performing final cleanup steps after upgrade

2. データベースの書き込みを防止するためにメンテナンスモードにする

アップグレードプロセス中に、新しいデータは新しいデータベースに転送されないため、現在のプライマリデータベースに新しいデータが書き込まれないようにすることが重要です。これを行うには、アプリをメンテナンスモード​にします。スケジューラージョブも実行されている場合は、これを無効にします。

$ heroku maintenance:on -a example-app
Enabling maintenance mode for example-app... done

3. データを新しいデータベースに転送する

データを現在のデータベースから新しくプロビジョニングされたデータベースにコピーするには、新しい​データベースの HEROKU_POSTGRESQL_COLOR​ 名を指定して pg:copy​ コマンドを使用します。

この例では、DATABASE_URL​ が転送するデータのソースであり、HEROKU_POSTGRESQL_PINK​ がターゲットデータベースです。

$ heroku pg:copy DATABASE_URL HEROKU_POSTGRESQL_PINK --app example-app

!    WARNING: Destructive Action
!    Transfering data from DATABASE_URL to HEROKU_POSTGRESQL_PINK
!    This command will affect the app: example-app
!    To proceed, type "example-app" or re-run this command with --confirm example-app

> example-app

新しいデータベースのアドオン名 (例: ​postgresql-concave-52656​) も使用できます。

$ heroku pg:copy DATABASE_URL postgresql-concave-52656 --app example-app

4. 新しいデータベースをプロモートまたはアタッチする

DATABASE_URL​ が以前のプライマリデータベースの環境設定​だった場合は、pg:promote​ を使用して新しくアップグレードしたデータベースを新しい DATABASE_URL​ としてプロモートします。pg:promote​ では、新しい HEROKU_POSTGRESQL_<color>_URL​ 環境設定に割り当てられた、古いプライマリデータベースの代替アタッチメントが作成されます。このプロモーションプロセスによってリリースがトリガーされ、アプリが再起動されます。

$ heroku pg:promote HEROKU_POSTGRESQL_PINK --app example-app
Promoting HEROKU_POSTGRESQL_PINK_URL to DATABASE_URL... done

アプリはまだ新しいリクエストを受信して​​いませんが、これで手順 1 で作成した​データベースがアプリのプライマリデータベース (DATABASE_URL​) になりました。

アップグレードするデータベースにデフォルトの DATABASE_URL​ とは異なる環境設定がある場合は、heroku addons:attach を使用して、必要なエイリアスまたはアタッチメント名で新しくアップグレードしたデータベースをプロモートします。元のプライマリデータベースが複数のアプリにアタッチされていた場合は、addons:attach​ を使用して新たにアップグレードされたデータベースをこれらのアプリにアタッチする必要があります。

$ heroku addons:create heroku-postgresql:standard-0 -a example-app -- --follow DATABASE_URL

$ heroku addons:create heroku-postgresql:standard-0 --follow DATABASE_URL -a example-app

5. メンテナンスモードを終了する

通常のアプリケーション操作を再開するには、Web 以外のすべての dyno をその元のレベルにスケーリングします (heroku ps:scale worker=1​ など)。

最後に、メンテナンスモードをオフにします。

$ heroku maintenance:off --app example-app

アプリケーションが、新しいデータベースインスタンスへのリクエストを受信するようになりました。これは、heroku pg:info​ を実行することによって確認できます。DATABASE_URL​ で示されるデータベースはプライマリデータベースと見なされます。

古いプライマリデータベースのプロビジョニング解除

データベースをアップグレードした後、古いプライマリデータベースを必ずプロビジョニング解除してください。

$ heroku addons:destroy HEROKU_POSTGRESQL_LAVENDER --app example-app