跳到主要内容

从抢先体验版升级

本指南将向您展示如何将您的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_dumppg_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.