从现有数据库导入

PostgreSQL

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

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

创建一个新的 Prisma Postgres 数据库。
通过 pg_dump 导出您现有的数据。
通过 pg_restore 将先前导出的数据导入到 Prisma Postgres 中。

在第三步中，您将使用 TCP 隧道安全地连接到您的 Prisma Postgres 数据库，以便运行 pg_restore。

先决条件

现有 PostgreSQL 数据库的连接 URL
一个账户
已安装 Node.js 18+
PostgreSQL CLI 工具 (pg_dump, pg_restore)，用于创建和恢复备份

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

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

登录到并打开控制台。
在您选择的工作区中，单击 New project（新建项目）按钮。
在 Name（名称）字段中，键入项目的名称，例如 hello-ppg。
在 Prisma Postgres 部分，单击 Get started（开始使用）按钮。
在 Region（区域）下拉列表中，选择离您当前位置最近的区域，例如 US East (N. Virginia)（美国东部（弗吉尼亚州北部））。
单击 Create project（创建项目）按钮。

数据库配置完成后，在 Set up database access（设置数据库访问权限）部分找到您的 Prisma Postgres 连接 URL 并保存以备后用，您将在步骤 3 中需要它。

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

在这一步中，您将从现有数据库导出数据，并将其存储在本地机器上的 .bak 文件中。

确保准备好现有数据库的连接 URL，它应该像这样结构化

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

展开下方以查看特定于提供商的说明，这些说明可帮助您确定正确的连接字符串

Neon

确保通过关闭 Connection pooling（连接池）切换来选择非池化连接字符串。
sslmode 必须设置为 require 并附加到您的 Neon 数据库 URL，命令才能正常工作。

连接 URL 应类似于这样

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

Supabase

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

连接 URL 应类似于这样

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

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

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

以下是此命令中使用的 CLI 选项的快速概述

-Fc: 为备份使用自定义格式，推荐用于 pg_restore
-v: 在 verbose 模式下运行 pg_dump
-d: 指定数据库连接字符串
-n: 指定目标 PostgreSQL schema
-f: 指定备份文件的输出名称

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

3. 将数据导入到 Prisma Postgres

在这一步中，您将使用 TCP 隧道连接到您的 Prisma Postgres 实例，并通过 pg_restore 导入数据。

您还需要步骤 1 中的 Prisma Postgres 连接 URL，它应该类似于这样

prisma+postgres://accelerate.prisma-data.net/?api_key=ey...

如果您在当前目录中已经有一个设置了 DATABASE_URL 的 .env 文件，隧道 CLI 将自动拾取它，无需手动导出。但是，如果您尚未设置 .env 文件，则需要显式设置 DATABASE_URL 环境变量。

要设置环境变量，请打开终端并将 DATABASE_URL 环境变量设置为您的 Prisma Postgres 数据库 URL 的值（将 __API_KEY__ 占位符替换为您实际数据库连接 URL 的 API 密钥）

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

注意

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

接下来，启动 TCP 隧道

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

显示CLI结果

Prisma Postgres auth proxy listening on 127.0.0.1:5433 🚀

Your connection is authenticated using your Prisma Postgres API key.
...

==============================
hostname:  127.0.0.1
port:      5433
username:  <anything>
password:  <none>
==============================

注意

保持您当前的终端窗口或选项卡打开，以便隧道进程继续运行，并且连接保持打开状态。

现在，使用上一步中的 db_dump.bak 备份文件，通过 pg_restore 命令将数据恢复到您的 Prisma Postgres 数据库中

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

注意

您无需为此命令提供用户名和密码凭据，因为 TCP 隧道已经通过 Prisma Postgres 连接 URL 中的 API 密钥对您进行了身份验证。

您现在已成功将数据从现有 PostgreSQL 数据库导入到 Prisma Postgres 🎉

要验证导入是否成功，您可以使用 Prisma Studio。在中打开它，方法是单击项目左侧边栏中的 Studio 选项卡，或者运行此命令以在本地启动 Prisma Studio

npx prisma studio

4. 更新您的应用程序代码以查询 Prisma Postgres

情景 A：您已经在使用 Prisma ORM

如果您已经在使用 Prisma ORM，那么您唯一需要做的就是

将 Prisma Accelerate 扩展添加到您的项目
更新数据库连接 URL 并重新生成 Prisma Client

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

当使用 Prisma Postgres 时，Prisma Accelerate 扩展是必需的。如果您当前未使用 Prisma Accelerate 和 Prisma ORM，请按照以下步骤使 Prisma ORM 与 Prisma Postgres 一起工作。

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

npm install @prisma/extension-accelerate

然后，将扩展添加到您的 Prisma Client 实例

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

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

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

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

schema.prisma

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

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

打开 .env 并更新 DATABASE_URL 环境变量的值以匹配您的 Prisma Postgres 连接 URL，使其看起来类似于这样

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

最后一步，您需要重新生成 Prisma Client，以便更新后的环境变量生效，并且您的查询在未来指向 Prisma Postgres

npx prisma generate --no-engine

完成此操作后，您可以运行您的应用程序，它应该像以前一样工作。

情景 B：您尚未使用 Prisma ORM

如果您尚未使用 Prisma ORM，则需要执行以下步骤才能从您的应用程序中使用 Prisma Postgres

在您的项目中安装 Prisma CLI
内省数据库以生成 Prisma schema
生成 Prisma Client
更新应用程序中的查询以使用 Prisma ORM

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

先决条件​

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

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

3. 将数据导入到 Prisma Postgres​

4. 更新您的应用程序代码以查询 Prisma Postgres​

情景 A：您已经在使用 Prisma ORM​

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

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

情景 B：您尚未使用 Prisma ORM​