从 Early Access 升级

本指南向你展示如何将 Prisma Postgres Early Access (EA) 数据库迁移到现在的官方 Prisma Postgres General Availability (GA) 数据库。Prisma Postgres Early Access 的推出是为了让早期采用者能够测试 Prisma 新的托管 PostgreSQL 服务。随着我们转向 GA，将数据从 EA 数据库安全地迁移到新的 GA 数据库至关重要。

¥This guide shows you how to migrate your Prisma Postgres Early Access (EA) database to the now official Prisma Postgres General Availability (GA) database. Prisma Postgres Early Access was introduced to allow early adopters to test Prisma’s new managed PostgreSQL service. As we move to GA, it's crucial to safely migrate data from your EA database to the new GA database.

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

¥Prisma will not automatically migrate your data to ensure its integrity. Instead, this process must be done manually. You can accomplish this in three main steps:

1. 通过 pg_dump 备份你的 EA 数据库。

   ¥Back up your EA database via pg_dump.

2. 创建一个新的 GA 数据库。

   ¥Create a new GA database.

3. 通过 pg_restore 将备份导入 GA 数据库。

   ¥Import your backup into the GA database via pg_restore.

我们将使用 @prisma/ppg-tunnel 包安全地连接到两个数据库。此工具设置了安全代理隧道，无需手动处理凭据。

¥We will be using the @prisma/ppg-tunnel package to securely connect to both databases. This tool sets up a secure proxy tunnel, eliminating the need for manual credential handling.

你可以在 此页面 上了解有关 Prisma Postgres 的更多信息。

¥You can learn more about Prisma Postgres on this page.

先决条件

¥Prerequisites

开始之前，请确保你已具备：

¥Before you begin, make sure you have:

• 已安装 Node.js（版本 16 或更高版本）。

  ¥Node.js installed (version 16 or higher).

• 用于创建和恢复备份的 PostgreSQL CLI 工具（pg_dump、pg_restore）。

  ¥PostgreSQL CLI Tools (pg_dump, pg_restore) for creating and restoring backups.

• Prisma Postgres 数据库的数据库连接字符串。

  ¥A Database connection string for your Prisma Postgres database.

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

¥To create and restore backups, ensure you have the PostgreSQL command-line tools installed. Run the following commands based on your operating system:

macOS

brew install postgresql@16
which pg_dump
which pg_restore

Windows

# Download from the official PostgreSQL website:
# https://www.postgresql.org/download/windows/
# During installation, select "Command Line Tools".
# Then verify with:

where pg_dump
where pg_restore

Linux

sudo apt-get update
sudo apt-get install postgresql-client-16
which pg_dump
which pg_restore

提示

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

¥If you installed PostgreSQL but still see a “command not found” error for pg_dump or pg_restore, ensure your installation directory is in your system’s PATH environment variable.

注意

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

¥Please make sure that you are installing Postgresql version 16. Other versions may cause errors during the backup and restore process.

选项 A:交互式方法

¥Option A: Interactive approach

如果你更喜欢引导式单命令解决方案，建议使用此方法。在此模式下，@prisma/ppg-tunnel CLI：

¥This approach is recommended if you prefer a guided, one-command solution. In this mode, the @prisma/ppg-tunnel CLI:

1. 提示你输入早期访问 (EA) 数据库 API 密钥（或 DATABASE_URL）。

   ¥Prompts you for your Early Access (EA) database API key (or DATABASE_URL).

2. 在后台使用 pg_dump 将你的 EA 数据库备份到当前目录中的文件中。

   ¥Uses pg_dump behind the scenes to back up your EA database to a file in the current directory.

3. 提示你输入新的 GA 数据库 URL 或 API 密钥。

   ¥Prompts you for your new GA database URL or API Key.

4. 使用 pg_restore 将备份文件导入你的 GA 数据库。

   ¥Uses pg_restore to import the backup file into your GA database.

交互模式不接受任何 CLI 参数或从环境中读取 API 密钥。你必须以交互方式提供它们。

¥Interactive mode does not accept any CLI arguments or read API keys from the environment. You must provide them interactively.

步骤

¥Steps

1. 打开终端并运行：

   ¥Open a terminal and run:

npx @prisma/ppg-tunnel migrate-from-ea

2. 提示时，粘贴你的 Early Access 数据库密钥或连接字符串。CLI 将在当前目录中创建一个 .bak 文件。

   ¥When prompted, paste your Early Access database key or connection string. The CLI will create a .bak file in the current directory.

3. 再次提示时，粘贴你的 GA 数据库密钥或连接字符串。CLI 将自动将 .bak 文件还原到新的 GA 数据库中。

   ¥When prompted again, paste your GA database key or connection string. The CLI will automatically restore the .bak file into the new GA database.

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

   ¥Once complete, connect with your favorite Database IDE to verify your data in the GA database.

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

¥Option B: Manual backup-and-restore approach

如果你更喜欢或需要更好地控制迁移过程（或直接传递环境变量），请按照以下手动步骤操作。迁移涉及三个主要部分：

¥If you prefer or need finer control over the migration process (or to pass environment variables directly), follow these manual steps. The migration involves three main parts:

1. 通过 pg_dump 备份你的 EA 数据库。

   ¥Back up your EA database via pg_dump.

2. 创建一个新的 GA 数据库。

   ¥Create a new GA database.

3. 通过 pg_restore 将备份导入 GA 数据库。

   ¥Import your backup into the GA database via pg_restore.

我们仍将使用 @prisma/ppg-tunnel 包安全地连接到两个数据库。

¥We will still be using the @prisma/ppg-tunnel package to securely connect to both databases.

1. 备份 EA 数据库

¥ Back up the EA database

1.1.使用 @prisma/ppg-tunnel 直接连接到 EA 数据库

¥1.1. Connecting to the EA database directly with @prisma/ppg-tunnel

在你的终端中，运行 npx @prisma/ppg-tunnel 以建立到 Early Access 数据库的安全隧道。

¥In your terminal, run npx @prisma/ppg-tunnel to establish a secure tunnel to your Early Access database.

如果你当前目录中已经有一个 .env 文件并且设置了 DATABASE_URL，隧道 CLI 将自动获取它 - 无需手动导出它。但是，如果你尚未设置 .env 文件，则需要明确设置 DATABASE_URL 环境变量。

¥If you already have a .env file in your current directory with DATABASE_URL set, the tunnel CLI will automatically pick it up—no need to manually export it. However, if you haven't set up a .env file, you'll need to set the DATABASE_URL environment variable explicitly.

要设置环境变量（使用你的实际 EA 数据库 URL）：

¥To set environment variable (with your actual EA database URL):

export DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=eyJhbGciOiJIUzI..."

注意

如果你在终端中明确设置了 DATABASE_URL，则该值将优先于 .env 文件中的值。

¥If you explicitly set DATABASE_URL in your terminal, that value will take precedence over the one in your .env file.

运行隧道：

¥Run the tunnel:

npx @prisma/ppg-tunnel --host 127.0.0.1  --port 5432

你应该看到类似以下内容的输出：

¥You should see output similar to:

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>
==============================

注意

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

¥Please note that the port you will see in your output will be a randomly assigned port which may be different from the one mentioned here. Also, Keep this terminal window open so the tunnel remains active! If you close it, the tunnel disconnects.

从终端输出复制端口号，你将在下一步中需要它来执行 pg_dump 命令。

¥Copy the port number from the terminal output, you’ll need it in the next step for the pg_dump command.

1.2.使用 pg_dump 创建备份

¥1.2. Creating the Backup with pg_dump

在隧道运行时，你现在可以通过运行以下命令转储 EA 数据库：

¥With the tunnel running, you can now dump the EA database by running the following command:

PGSSLMODE=disable \
pg_dump \
  -h 127.0.0.1 \
  -p 5432 \
  -Fc \
  -v \
  -d postgres \
  -f ./mydatabase.bak \
&& echo "-complete-"

PGSSLMODE=disable 表示本地不需要 SSL，因为隧道已经加密了连接。

¥PGSSLMODE=disable indicates SSL is not required locally because the tunnel already encrypts the connection.

`-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 的备份文件。我们将在后续步骤中使用此备份文件进行导入。

¥This should create your backup file named mydatabase.bak in the current directory. We will use this backup file for importing in next steps.

2. 创建新的 GA 数据库

¥ Create a new GA database

接下来，创建你的 GA（通用可用性）数据库：

¥Next, create your GA (General Availability) database:

1. 访问 并登录（或创建账户）。

   ¥Visit and sign in (or create an account).

2. 在你选择的区域中创建一个 Prisma Postgres 数据库。

   ¥Create a Prisma Postgres database in the region of your choice.

3. 复制数据库 URL 以供日后使用。

   ¥Copy the Database URL for later use.

Prisma Postgres GA 使用 PostgreSQL 17，因此你将把 EA 备份恢复到这个新环境中。

¥Prisma Postgres GA uses PostgreSQL 17, so you’ll be restoring your EA backup into this new environment.

3. 将备份导入 GA 数据库

¥ Import the backup into the GA database

3.1.使用 @prisma/ppg-tunnel 连接到 GA 数据库

¥3.1. Connecting to the GA Database with @prisma/ppg-tunnel

打开一个新终端（或停止之前的隧道）并连接到你的 GA 数据库：

¥Open a new terminal (or stop the previous tunnel) and connect to your GA database:

为新的 GA 数据库设置环境变量：

¥Set environment variables for the new GA database:

export DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=eyJhbGciOiJIUzI..."

运行隧道：

¥Run the tunnel:

npx @prisma/ppg-tunnel --host 127.0.0.1 --port 5432

你应该看到类似以下内容的输出：

¥You should see output similar to:

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>
==============================

注意

再次，保持此隧道进程运行以维持连接！

¥Again, keep this tunnel process running to maintain the connection!

3.2.使用 pg_restore 恢复备份

¥3.2. Restoring the Backup with pg_restore

通过运行以下命令，使用步骤 1 中的备份文件将数据恢复到使用 pg_restore 的 GA 数据库中：

¥Use the backup file from Step 1 to restore data into your GA database with pg_restore by running this command:

PGSSLMODE=disable \
pg_restore \
  -h 127.0.0.1 \
  -p 5432 \
  -v \
  -d postgres \
  ./mydatabase.bak \
&& echo "-complete-"

此外，在这种情况下，数据库名称为 postgres。你可以将其替换为所需的数据库名称。数据库的名称无关紧要，因为你将能够照常使用 Prisma Postgres。备份文件名（在我们的示例中为 mydatabase.bak）应与你在步骤 1 中创建的名称匹配。

¥Also, in this case the database name is postgres. You can replace it with your desired database name. It does not matter what you name your database as you will be able to use Prisma Postgres as usual. The backup file name (mydatabase.bak in our example) should match the one you created in Step 1.

此命令将备份恢复到 GA 数据库中。如果成功，你应该在终端中看到 -complete-。

¥This command restores the backup into the GA database. If successful, you should see -complete- in the terminal.

下一步

¥Next steps

连接你最喜欢的数据库 IDE 或 Prisma 客户端，以确认所有表、行和模式都与你的旧 EA 环境匹配。

¥Connect with your favorite Database IDE or Prisma Client to confirm all tables, rows, and schemas match your old EA environment.

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

¥Congratulations! You have successfully migrated your Prisma Postgres Early Access database to Prisma Postgres GA. If you encounter any issues, please reach out to our support team.