アーリーアクセスからのアップグレード

このガイドでは、Prisma Postgres Early Access (EA) データベースを、正式版となった Prisma Postgres General Availability (GA) データベースに移行する方法について説明します。Prisma Postgres Early Access は、早期導入者が Prisma の新しいマネージド PostgreSQL サービスをテストできるように導入されました。GA に移行するにあたり、EA データベースから新しい GA データベースへのデータ移行を安全に行うことが重要です。

Prisma は、データの整合性を確保するために、データを自動的に移行することはありません。代わりに、このプロセスは手動で行う必要があります。これは、主に次の 3 つのステップで実行できます。

pg_dump を使用して EA データベースをバックアップします。
新しい GA データベースを作成します。
pg_restore を使用して、バックアップを GA データベースにインポートします。

ここでは、@prisma/ppg-tunnel パッケージを使用して、両方のデータベースに安全に接続します。このツールは、手動での認証情報処理の必要性をなくし、セキュアなプロキシトンネルをセットアップします。

Prisma Postgres の詳細については、こちらのページをご覧ください。

前提条件

開始する前に、以下が揃っていることを確認してください。

Node.js がインストールされていること (バージョン 16 以降)。
バックアップを作成および復元するための PostgreSQL CLI ツール (pg_dump, pg_restore)。
Prisma Postgres データベースの データベース接続文字列。

バックアップを作成および復元するには、PostgreSQL コマンドラインツールがインストールされていることを確認してください。お使いのオペレーティングシステムに基づいて、次のコマンドを実行してください。

macOS
Windows
Linux

brew install postgresql@16
which pg_dump
which pg_restore

# Download from the official PostgreSQL website:
# https://www.postgresql.org/download/windows/
# During installation, select "Command Line Tools".
# Then verify with:

where pg_dump
where pg_restore

sudo apt-get update
sudo apt-get install postgresql-client-16
which pg_dump
which pg_restore

ヒント

PostgreSQL をインストールしても、pg_dump または pg_restore で「command not found」エラーが表示される場合は、インストールディレクトリがシステムの PATH 環境変数に含まれていることを確認してください。

注意

Postgresql バージョン 16 をインストールしていることを確認してください。他のバージョンでは、バックアップと復元プロセス中にエラーが発生する可能性があります。

オプション A: インタラクティブなアプローチ

このアプローチは、ガイド付きのワンコマンドソリューションを好む場合に推奨されます。このモードでは、@prisma/ppg-tunnel CLI は

Early Access (EA) データベース API キー (または DATABASE_URL) の入力を求めます。
pg_dump をバックグラウンドで使用して、EA データベースを現在のディレクトリのファイルにバックアップします。
新しい GA データベース URL または API キーの入力を求めます。
pg_restore を使用して、バックアップファイルを GA データベースにインポートします。

インタラクティブモードでは、CLI 引数を受け入れず、環境変数から API キーを読み取りません。インタラクティブに入力する必要があります。

手順

ターミナルを開き、次を実行します。

npx @prisma/ppg-tunnel migrate-from-ea

プロンプトが表示されたら、Early Access データベースキーまたは接続文字列を貼り付けます。CLI は、現在のディレクトリに .bak ファイルを作成します。
再度プロンプトが表示されたら、GA データベースキーまたは接続文字列を貼り付けます。CLI は、.bak ファイルを新しい GA データベースに自動的に復元します。
完了したら、お好みのデータベース IDE で接続し、GA データベースのデータを確認します。

オプション B: 手動バックアップと復元のアプローチ

移行プロセスをより細かく制御したい場合 (または環境変数を直接渡したい場合) は、以下の手動手順に従ってください。移行には、主に 3 つの部分が含まれます。

pg_dump を使用して EA データベースをバックアップします。
新しい GA データベースを作成します。
pg_restore を使用して、バックアップを GA データベースにインポートします。

引き続き @prisma/ppg-tunnel パッケージを使用して、両方のデータベースに安全に接続します。

1. EA データベースをバックアップする

1.1. `@prisma/ppg-tunnel` で EA データベースに直接接続する

ターミナルで npx @prisma/ppg-tunnel を実行して、Early Access データベースへのセキュアなトンネルを確立します。

現在のディレクトリに DATABASE_URL が設定された .env ファイルが既にある場合、トンネル CLI はそれを自動的に取得するため、手動でエクスポートする必要はありません。ただし、.env ファイルを設定していない場合は、DATABASE_URL 環境変数を明示的に設定する必要があります。

環境変数を設定するには (実際の EA データベース URL を使用)

export DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=eyJhbGciOiJIUzI..."

注意

ターミナルで DATABASE_URL を明示的に設定した場合、その値は .env ファイルの値よりも優先されます。

トンネルを実行します。

npx @prisma/ppg-tunnel --host 127.0.0.1  --port 5432

次のような出力が表示されます。

Prisma Postgres auth proxy listening on 127.0.0.1:5432 🚀

Your connection is authenticated using your Prisma Postgres API key.
...

==============================
hostname:  127.0.0.1
port:      5432
username:  <anything>
password:  <none>
==============================

注意

出力に表示されるポートは、ここに記載されているポートとは異なるランダムに割り当てられたポートになる場合があることに注意してください。また、このターミナルウィンドウを開いたままにして、トンネルをアクティブに保ってください。閉じると、トンネルが切断されます。

ターミナル出力からポート番号をコピーします。次のステップの pg_dump コマンドで必要になります。

1.2. `pg_dump` でバックアップを作成する

トンネルが実行されている状態で、次のコマンドを実行して EA データベースをダンプできます。

PGSSLMODE=disable \
pg_dump \
  -h 127.0.0.1 \
  -p 5432 \
  -Fc \
  -v \
  -d postgres \
  -f ./mydatabase.bak \
&& echo "-complete-"

PGSSLMODE=disable は、トンネルが既に接続を暗号化しているため、ローカルでは SSL が不要であることを示します。

`-h` is the host (127.0.0.1)
`-p` is the port, which should match the one from the tunnel output.
`-Fc` uses the custom format for backups, recommended for pg_restore.
`-d` postgres is the default database name used in Prisma Postgres.
`-f` ./mydatabase.bak specifies the backup file name and location.
`-v` runs pg_dump in verbose mode.

これにより、現在のディレクトリに mydatabase.bak という名前のバックアップファイルが作成されます。このバックアップファイルは、次のステップでのインポートに使用します。

2. 新しい GA データベースを作成する

次に、GA (General Availability) データベースを作成します。

アクセスしてサインイン (またはアカウントを作成) します。
任意のリージョンに Prisma Postgres データベースを作成します。
後で使用するために、データベース URL をコピーします。

Prisma Postgres GA は PostgreSQL 17 を使用するため、EA バックアップをこの新しい環境に復元します。

3. バックアップを GA データベースにインポートする

3.1. `@prisma/ppg-tunnel` で GA データベースに接続する

新しいターミナルを開き (または前のトンネルを停止し)、GA データベースに接続します。

新しい GA データベースの環境変数を設定します。

export DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=eyJhbGciOiJIUzI..."

トンネルを実行します。

npx @prisma/ppg-tunnel --host 127.0.0.1 --port 5432

次のような出力が表示されます。

Prisma Postgres auth proxy listening on 127.0.0.1:52604 🚀

Your connection is authenticated using your Prisma Postgres API key.
...

==============================
hostname:  127.0.0.1
port:      52604
username:  <anything>
password:  <none>
==============================

注意

繰り返しますが、接続を維持するために、このトンネルプロセスを実行し続けてください。

3.2. `pg_restore` でバックアップを復元する

ステップ 1 のバックアップファイルを使用して、次のコマンドを実行して pg_restore でデータを GA データベースに復元します。

PGSSLMODE=disable \
pg_restore \
  -h 127.0.0.1 \
  -p 5432 \
  -v \
  -d postgres \
  ./mydatabase.bak \
&& echo "-complete-"

また、この場合、データベース名は postgres です。これは、目的のデータベース名に置き換えることができます。Prisma Postgres は通常どおり使用できるため、データベースの名前は重要ではありません。バックアップファイル名 (この例では mydatabase.bak) は、ステップ 1 で作成したファイル名と一致する必要があります。

このコマンドは、バックアップを GA データベースに復元します。成功すると、ターミナルに -complete- と表示されます。

次のステップ

お好みのデータベース IDE または Prisma Client で接続し、すべてのテーブル、行、およびスキーマが古い EA 環境と一致することを確認します。

おめでとうございます。Prisma Postgres Early Access データベースから Prisma Postgres GA への移行が成功しました。問題が発生した場合は、サポートチームにお問い合わせください。

前提条件​

オプション A: インタラクティブなアプローチ​

手順​

オプション B: 手動バックアップと復元のアプローチ​

1. EA データベースをバックアップする​

1.1. @prisma/ppg-tunnel で EA データベースに直接接続する​

1.2. pg_dump でバックアップを作成する​

2. 新しい GA データベースを作成する​

3. バックアップを GA データベースにインポートする​

3.1. @prisma/ppg-tunnel で GA データベースに接続する​

3.2. pg_restore でバックアップを復元する​

次のステップ​