跳到主要内容

从抢先体验版升级

本指南将向您展示如何将您的Prisma Postgres抢先体验版 (EA) 数据库迁移到现已正式发布的Prisma Postgres通用版 (GA) 数据库。Prisma Postgres抢先体验版旨在让早期采用者测试Prisma新的托管式PostgreSQL服务。随着我们转向通用版，安全地将数据从EA数据库迁移到新的GA数据库至关重要。

Prisma 不会自动迁移您的数据，以确保其完整性。相反，此过程必须手动完成。您可以通过以下三个主要步骤来完成此操作：

  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的“命令未找到”错误，请确保您的安装目录已添加到系统的PATH环境变量中。

注意

请确保您安装的是PostgreSQL 16版本。其他版本在备份和恢复过程中可能会导致错误。

选项A：交互式方法​

如果您喜欢引导式、一键式解决方案，推荐使用此方法。在此模式下，@prisma/ppg-tunnel CLI将：

  1. 提示您输入抢先体验版 (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. 当提示时，粘贴您的抢先体验版数据库密钥或连接字符串。CLI将在当前目录中创建一个.bak文件。

  2. 当再次提示时，粘贴您的GA数据库密钥或连接字符串。CLI将自动将.bak文件恢复到新的GA数据库中。

  3. 完成后，使用您喜欢的数据库IDE连接以验证GA数据库中的数据。

选项B：手动备份和恢复方法​

如果您喜欢或需要对迁移过程进行更精细的控制（或直接传递环境变量），请遵循以下手动步骤。迁移涉及三个主要部分：

  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以建立与您的抢先体验版数据库的安全隧道。

如果您当前目录中已有一个设置了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（通用版）数据库：

  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 Client连接，以确认所有表、行和架构都与您的旧EA环境匹配。

恭喜！您已成功将您的Prisma Postgres抢先体验版数据库迁移到Prisma Postgres通用版。如果您遇到任何问题，请联系我们的支持团队。

© . All rights reserved.