跳到主要内容

从 Early Access 升级

本指南将向您展示如何将您的 Prisma Postgres Early Access (EA) 数据库迁移到现已正式发布的 Prisma Postgres General Availability (GA) 数据库。引入 Prisma Postgres Early Access 是为了让早期采用者测试 Prisma 新的托管式 PostgreSQL 服务。随着我们迁移到 GA，安全地将数据从 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 的“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：手动备份和恢复方法​

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

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

恭喜！您已成功将您的 Prisma Postgres Early Access 数据库迁移到 Prisma Postgres GA。如果您遇到任何问题，请联系我们的支持团队。