从现有数据库导入数据

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

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.

创建 Prisma Postgres 实例后，你可以进入下一步。

¥With your Prisma Postgres instance being created, you can move to the next step.

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

在本节中，你将使用 TCP 隧道 连接到你的 Prisma Postgres 实例并通过 pg_restore 导入数据。

¥In this section, you'll use a TCP Tunnel in order to connect to your Prisma Postgres instance and import data via pg_restore.

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

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

打开一个新终端，并设置 Prisma Postgres 数据库连接 URL 的环境变量。

¥Open a new terminal and set the environment variable for your Prisma Postgres database connection URL.

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

注意

保持此隧道进程运行以维护连接！

¥Keep this tunnel process running to maintain the connection!

3.2.使用 pg_restore 恢复备份

¥3.2. Restoring the Backup with pg_restore

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

¥Use the backup file from Step 2 to restore data into Prisma Postgres database with pg_restore by running this command:

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

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

¥Once the command completes execution, you will have successfully imported the data from your 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，那么你唯一需要做的事情是：

¥If you already using Prisma ORM, the only things you need to do are:

• 将 Prisma Accelerate 扩展添加到你的项目

  ¥add the Prisma Accelerate extension to your project

• 更新数据库连接 URL 并重新生成 Prisma 客户端

  ¥update the database connection URL and re-generate Prisma Client

4.A.1.添加 Prisma Accelerate 扩展

¥4.A.1. Add the Prisma Accelerate extension

使用 Prisma Postgres 时，Prisma Accelerate 扩展为 required。如果你目前没有将 Prisma Accelerate 与 Prisma ORM 一起使用，请按照以下步骤使 Prisma ORM 与 Prisma Postgres 配合使用。

¥Th Prisma Accelerate extension is required when using Prisma Postgres. If you are not currently using Prisma Accelerate with Prisma ORM, go through the following steps to make Prisma ORM work with Prisma Postgres.

首先，在你的项目中安装 @prisma/extension-accelerate 包：

¥First, install the @prisma/extension-accelerate package in your project:

npm install @prisma/extension-accelerate

然后，将扩展添加到你的 Prisma 客户端实例：

¥Then, add the extension to your Prisma Client instance:

import { withAccelerate } from '@prisma/extension-accelerate'

const prisma = new PrismaClient().$extends(withAccelerate())

4.A.2.更新数据库连接 URL

¥4.A.2. Update the database connection URL

数据库连接 URL 通过 schema.prisma 文件中 datasource 块的 url 配置。最常见的是，它是通过名为 DATABASE_URL 的环境变量设置的：

¥The database connection URL is configured via the url of the datasource block in your schema.prisma file. Most commonly, it is set via an environment variable called DATABASE_URL:

schema.prisma

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

接下来的步骤假设你是 .env 文件来设置 DATABASE_URL 环境变量（如果不是这种情况，你可以按照你喜欢的方式设置环境变量）。

¥The next steps assumes that you're a .env file to set the DATABASE_URL environment variable (if that's not the case, you can set the environment variable in your preferred way).

打开 .env 并更新 DATABASE_URL 环境变量的值以匹配你的 Prisma Postgres 连接 URL，类似于此：

¥Open .env and update the value for the DATABASE_URL environment variable to match your Prisma Postgres connection URL, looking similar to this:

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

最后一步，你需要重新生成 Prisma Client，以便更新的环境变量生效，并且你的查询将转到 Prisma Postgres：

¥As a last step, you need to re-generate Prisma Client for so that the updated environment variables takes effect and your queries go to Prisma Postgres going forward:

npx prisma generate --no-engine

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

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

场景 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 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.