从抢先体验版升级
本指南将向您展示如何将您的Prisma Postgres抢先体验版 (EA) 数据库迁移到现已正式发布的Prisma Postgres通用版 (GA) 数据库。Prisma Postgres抢先体验版旨在让早期采用者测试Prisma新的托管式PostgreSQL服务。随着我们转向通用版,安全地将数据从EA数据库迁移到新的GA数据库至关重要。
Prisma 不会自动迁移您的数据,以确保其完整性。相反,此过程必须手动完成。您可以通过以下三个主要步骤来完成此操作:
- 通过
pg_dump
备份您的EA数据库。 - 创建一个新的GA数据库。
- 通过
pg_restore
将您的备份导入到GA数据库中。
我们将使用@prisma/ppg-tunnel
包来安全连接两个数据库。此工具建立了一个安全的代理隧道,无需手动处理凭证。
您可以在此页面上了解更多关于Prisma Postgres的信息。
先决条件
在开始之前,请确保您已具备:
- 已安装Node.js(版本16或更高)。
- 用于创建和恢复备份的PostgreSQL CLI工具(
pg_dump
,pg_restore
)。 - 您的Prisma Postgres数据库的数据库连接字符串。
要创建和恢复备份,请确保您已安装PostgreSQL命令行工具。根据您的操作系统运行以下命令:
- macOS
- Windows
- Linux
brew install postgresql@16
which pg_dump
which pg_restore
# Download from the official PostgreSQL website:
# https://postgresql.ac.cn/download/windows/
# During installation, select "Command Line Tools".
# Then verify with:
where pg_dump
where pg_restore
sudo apt-get update
sudo apt-get install postgresql-client-16
which pg_dump
which pg_restore
如果您已安装PostgreSQL,但仍然看到pg_dump
或pg_restore
的“命令未找到”错误,请确保您的安装目录已添加到系统的PATH环境变量中。
请确保您安装的是PostgreSQL 16版本。其他版本在备份和恢复过程中可能会导致错误。
选项A:交互式方法
如果您喜欢引导式、一键式解决方案,推荐使用此方法。在此模式下,@prisma/ppg-tunnel
CLI将:
- 提示您输入抢先体验版 (EA) 数据库API密钥(或
DATABASE_URL
)。 - 在后台使用
pg_dump
将您的EA数据库备份到当前目录中的一个文件。 - 提示您输入新的GA数据库URL或API密钥。
- 使用
pg_restore
将备份文件导入到您的GA数据库。
交互模式不接受任何CLI参数或从环境中读取API密钥。您必须以交互方式提供它们。
步骤
- 打开终端并运行:
npx @prisma/ppg-tunnel migrate-from-ea
-
当提示时,粘贴您的抢先体验版数据库密钥或连接字符串。CLI将在当前目录中创建一个
.bak
文件。 -
当再次提示时,粘贴您的GA数据库密钥或连接字符串。CLI将自动将.bak文件恢复到新的GA数据库中。
-
完成后,使用您喜欢的数据库IDE连接以验证GA数据库中的数据。
选项B:手动备份和恢复方法
如果您喜欢或需要对迁移过程进行更精细的控制(或直接传递环境变量),请遵循以下手动步骤。迁移涉及三个主要部分:
- 通过
pg_dump
备份您的EA数据库。 - 创建一个新的GA数据库。
- 通过
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(通用版)数据库:
- 访问并登录(或创建帐户)。
- 在您选择的区域创建一个Prisma Postgres数据库。
- 复制数据库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通用版。如果您遇到任何问题,请联系我们的支持团队。