Skip to main content

从现有 PostgreSQL 数据库导入数据

本指南提供了将数据从现有 PostgreSQL 数据库导入 Prisma Postgres 的分步说明。

¥This guide provides step-by-step instructions for importing data from an existing PostgreSQL database into Prisma Postgres.

你可以通过三个步骤完成此迁移：

¥You can accomplish this migration in three steps:

  1. 创建一个新的 Prisma Postgres 数据库。

    ¥Create a new Prisma Postgres database.

  2. 通过 pg_dump 导出现有数据。

    ¥Export your existing data via pg_dump.

  3. 通过 pg_restore 将先前导出的数据导入 Prisma Postgres。

    ¥Import the previously exported data into Prisma Postgres via pg_restore.

在第三步中，你将使用 直接连接 安全地连接到 Prisma Postgres 数据库以运行 pg_restore。

¥In the third step, you will be using a direct connection to securely connect to your Prisma Postgres database to run pg_restore.

先决条件​

¥Prerequisites

  • 到现有 PostgreSQL 数据库的连接 URL

    ¥The connection URL to your existing PostgreSQL database

  • 账户

    ¥A account

  • 已安装 Node.js 18+

    ¥Node.js 18+ installed

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

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

确保你的 PostgreSQL 工具与 Prisma Postgres 版本匹配

Prisma Postgres 运行 PostgreSQL 17。你的 pg_dump 和 pg_restore 工具需要版本为 17 以确保兼容性。你可以通过运行 pg_dump --version 或 pg_restore --version 来检查你的版本。

¥Prisma Postgres runs PostgreSQL 17. Your pg_dump and pg_restore tools need to be version 17 to ensure compatibility. You can check your version by running pg_dump --version or pg_restore --version.

1. 创建新的 Prisma Postgres 数据库​

¥ Create a new Prisma Postgres database

按照以下步骤创建新的 Prisma Postgres 数据库：

¥Follow these steps to create a new Prisma Postgres database:

  1. 登录 并打开控制台。

    ¥Log in to and open the Console.

  2. 在你选择的 workspace 中，单击新建项目按钮。

    ¥In a workspace of your choice, click the New project button.

  3. 在名称字段中为你的项目输入一个名称，例如 hello-ppg。

    ¥Type a name for your project in the Name field, e.g. hello-ppg.

  4. 在 Prisma Postgres 部分中，单击“开始”按钮。

    ¥In the Prisma Postgres section, click the Get started button.

  5. 在“区域”下拉菜单中，选择最接近你当前位置的区域，例如美国东部（弗吉尼亚北部）。

    ¥In the Region dropdown, select the region that's closest to your current location, e.g. US East (N. Virginia).

  6. 单击创建项目按钮。

    ¥Click the Create project button.

数据库配置完成后，获取直接连接字符串：

¥Once your database is provisioned, obtain your direct connection string:

  1. 导航到活动的 Prisma Postgres 实例。

    ¥Navigate to your active Prisma Postgres instance.

  2. 点击项目侧边栏中的“API 密钥”选项卡。

    ¥Click the API Keys tab in the project's sidenav.

  3. 点击“创建 API 密钥”按钮。

    ¥Click the Create API key button.

  4. 在弹出窗口中，输入 API 密钥的名称，然后单击“创建”。

    ¥In the popup, provide a Name for the API key and click Create.

  5. 复制以 postgres:// 开头的连接字符串，这是你的直接连接字符串。

    ¥Copy the connection string starting with postgres://, this is your direct connection string.

保存连接字符串，你将在步骤 3 中用到它。

¥Save the connection string, you'll need it in step 3.

2. 从现有数据库导出数据​

¥ Export data from your existing database

在此步骤中，你将从现有数据库中导出数据并将其存储在本地计算机上的 .bak 文件中。

¥In this step, you're going to export the data from your existing database and store it in a .bak file on your local machine.

确保现有数据库的连接 URL 已准备好，它应该是这样的 structured：

¥Make sure to have the connection URL for your existing database ready, it should be structured like this:

postgresql://USER:PASSWORD@HOST:PORT/DATABASE

展开以下提供商特定的说明，帮助你确定正确的连接字符串：

¥Expand below for provider-specific instructions that help you determine the right connection string:

Neon

  • 确保通过关闭连接池切换来选择非池化连接字符串。

    ¥Make sure to select non-pooled connection string by switching off the Connection pooling toggle.

  • 必须将 sslmode 设置为 require 并附加到 Neon 数据库 URL 才能使命令正常工作。

    ¥The sslmode has to be set to require and appended to your Neon database url for the command to work.

  • 连接 URL 应类似于此：

    ¥The connection URL should look similar to this:

    postgresql://USER:PASSWORD@YOUR-NEON-HOST/DATABASE?sslmode=require
Supabase

  • 使用使用 Supavisor 会话模式 的数据库连接 URL。

    ¥Use a database connection URL that uses Supavisor session mode.

  • 连接 URL 应类似于此：

    ¥The connection URL should look similar to this:

    postgres://postgres.apbkobhfnmcqqzqeeqss:[YOUR-PASSWORD]@aws-0-ca-central-1.pooler.supabase.com:5432/postgres

接下来，运行以下命令导出 PostgreSQL 数据库的数据（将 __DATABASE_URL__ 占位符替换为你的实际数据库连接 URL）：

¥Next, run the following command to export the data of your PostgreSQL database (replace the __DATABASE_URL__ placeholder with your actual database connection URL):

pg_dump \
  -Fc \
  -v \
  -d __DATABASE_URL__ \
  -n public \
  -f db_dump.bak

以下是用于此命令的 CLI 选项的快速概述：

¥Here's a quick overview of the CLI options that were used for this command:

  • -Fc：使用自定义格式进行备份，推荐用于 pg_restore

    ¥-Fc: Uses the custom format for backups, recommended for pg_restore

  • -v：以详细模式运行 pg_dump

    ¥-v: Runs pg_dump in verbose mode

  • -d：指定数据库连接字符串

    ¥-d: Specifies the database connection string

  • -n：指定目标 PostgreSQL 模式

    ¥-n: Specifies the target PostgreSQL schema

  • -f：指定备份文件的输出名称

    ¥-f: Specifies the output name for the backup file

运行此命令将创建一个名为 db_dump.bak 的备份文件，你将在下一步中使用该文件将数据恢复到 Prisma Postgres 数据库中。

¥Running this command will create a backup file named db_dump.bak which you will use to restore the data into your Prisma Postgres database in the next step.

3. 将数据导入 Prisma Postgres​

¥ Import data into Prisma Postgres

在本节中，你将使用 直接连接字符串 连接到 Prisma Postgres 实例，并通过 pg_restore 导入数据。

¥In this section, you'll use your direct connection string to connect to your Prisma Postgres instance and import data via pg_restore.

步骤 1 中的直接连接字符串应如下所示：

¥Your direct connection string from step 1 should look like this:

postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require

使用步骤 2 中的备份文件，通过运行以下命令，使用 pg_restore 将数据恢复到 Prisma Postgres 数据库中（将 __USER__ 和 __PASSWORD__ 替换为你的直接连接中的值）。字符串）：

¥Use the backup file from Step 2 to restore data into your Prisma Postgres database with pg_restore by running this command (replace __USER__, __PASSWORD__ with the values from your direct connection string):

pg_restore \
  -h db.prisma.io \
  -p 5432 \
  -U __USER__ \
  -d postgres \
  -v \
  ./db_dump.bak \
&& echo "-complete-"

出现提示时，请输入直接连接字符串中的 __PASSWORD__。

¥When prompted, enter the __PASSWORD__ from your direct connection string.

提示

你还可以使用完整的连接字符串格式：

¥You can also use the full connection string format:

pg_restore \
  -d "postgres://USER:PASSWORD@db.prisma.io:5432/postgres?sslmode=require" \
  -v \
  ./db_dump.bak \
&& echo "-complete-"

命令执行完成后，你将成功将数据从现有 PostgreSQL 数据库导入 Prisma Postgres。 🎉

¥Once the command completes execution, you will have successfully imported the data from your existing PostgreSQL database into Prisma Postgres 🎉

要验证导入是否有效，你可以使用 Prisma 工作室。通过单击项目左侧导航栏中的 Studio 选项卡在 中打开它，或运行此命令在本地启动 Prisma Studio：

¥To validate that the import worked, you can use Prisma Studio. Either open it in the by clicking the Studio tab in the left-hand sidenav in your project or run this command to launch Prisma Studio locally:

npx prisma studio

4. 更新你的应用代码以查询 Prisma Postgres​

¥ Update your application code to query Prisma Postgres

场景 A:你已经在使用 Prisma ORM​

¥Scenario A: You are already using Prisma ORM

如果你已经在使用 Prisma ORM，则需要更新数据库连接 URL 以指向新的 Prisma Postgres 实例。

¥If you're already using Prisma ORM, you need to update your database connection URL to point to your new Prisma Postgres instance.

更新 .env 文件中的 DATABASE_URL，使其与步骤 1 中的 Prisma Postgres 直接连接字符串匹配：

¥Update the DATABASE_URL in your .env file to match your Prisma Postgres direct connection string from step 1:

.env
DATABASE_URL="postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require"

然后，重新生成 Prisma 客户端，以便更新的环境变量生效：

¥Then, re-generate Prisma Client so that the updated environment variable takes effect:

npx prisma generate

完成后，你可以运行应用，它应该可以像以前一样工作。

¥Once this is done, you can run your application and it should work as before.

提示

有关从头开始设置 Prisma ORM 和 Prisma Postgres 的完整指南（包括驱动程序适配器配置和最佳实践），请参阅 Prisma ORM 与 Prisma Postgres 快速入门 文件。

¥For a complete guide on setting up Prisma ORM with Prisma Postgres from scratch, including driver adapter configuration and best practices, see the Prisma ORM with Prisma Postgres quickstart.

场景 B:你尚未使用 Prisma ORM​

¥Scenario B: You are not yet using Prisma ORM

如果你尚未使用 Prisma ORM，则需要按照以下步骤从你的应用中使用 Prisma Postgres：

¥If you are not yet using Prisma ORM, you'll need to go through the following steps to use Prisma Postgres from your application:

  1. 在项目中安装 Prisma CLI 和其他必需的依赖：

    ¥Install the Prisma CLI and other required dependencies in your project

  2. 自省数据库以生成 Prisma 模式

    ¥Introspect the database to generate a Prisma schema

  3. 生成 Prisma 客户端

    ¥Generate Prisma Client

  4. 更新应用中的查询以使用 Prisma ORM

    ¥Update the queries in your application to use Prisma ORM

你可以在本指南中找到此过程的详细分步说明：将 Prisma ORM 添加到现有项目。

¥You can find the detailed step-by-step instructions for this process in this guide: Add Prisma ORM to an existing project.