跳到主要内容

从 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 数据库的 数据库连接字符串。

1. 备份 EA 数据库​

1.1. 安装 PostgreSQL 实用程序​

要创建和恢复备份，请确保您已安装 PostgreSQL 命令行工具。根据您的操作系统运行以下命令

brew install postgresql@16
which pg_dump
which pg_restore
提示

如果您已安装 PostgreSQL，但仍然看到 pg_dump 或 pg_restore 的“命令未找到”错误，请确保您的安装目录在系统的 PATH 环境变量中。

注意

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

1.2. 使用 @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>
==============================
注意

请注意，您在输出中看到的端口将是一个随机分配的端口，可能与此处提到的端口不同。此外，保持此终端窗口打开，以便隧道保持活动状态！如果您关闭它，隧道将断开连接。

  1. 从终端输出中复制端口号，您将在下一步的 pg_dump 命令中需要它。

1.3. 使用 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 Early Access 数据库迁移到 Prisma Postgres GA。如果您遇到任何问题，请联系我们的支持团队。