メインコンテンツへスキップ

Early Accessからのアップグレード

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

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

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

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

Prisma Postgresについてはこちらのページで詳しく学べます。

前提条件​

始める前に、以下の準備が整っていることを確認してください

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

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

brew install postgresql@16
which pg_dump
which pg_restore
ヒント

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

注

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

オプションA：対話型アプローチ​

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

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

対話モードでは、CLI引数を受け入れたり、環境からAPIキーを読み取ったりすることはありません。それらは対話的に提供する必要があります。

ステップ​

  1. ターミナルを開き、以下を実行します
npx @prisma/ppg-tunnel migrate-from-ea

  1. プロンプトが表示されたら、Early Accessデータベースキーまたは接続文字列を貼り付けます。CLIは現在のディレクトリに.bakファイルを作成します。

  2. 再度プロンプトが表示されたら、GAデータベースキーまたは接続文字列を貼り付けます。CLIは自動的に.bakファイルを新しいGAデータベースに復元します。

  3. 完了したら、お気に入りのデータベースIDEで接続し、GAデータベースのデータを検証してください。

オプションB：手動バックアップ・リストアアプローチ​

移行プロセスをより細かく制御したい場合（または環境変数を直接渡したい場合）は、これらの手動手順に従ってください。移行は主に3つのパートで構成されます

  1. pg_dumpを使用してEAデータベースをバックアップします。
  2. 新しいGAデータベースを作成します。
  3. 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) データベースを作成します

  1. アクセス先でサインインします（またはアカウントを作成します）。
  2. お好みのリージョンにPrisma Postgresデータベースを作成します。
  3. 後で使用するために、データベース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クライアントで接続し、すべてのテーブル、行、スキーマが古いEA環境と一致することを確認します。

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

© . All rights reserved.