将 Prisma ORM 添加到现有 PlanetScale 项目

PlanetScale 是一个无服务器数据库平台。本指南涵盖了 PlanetScale MySQL，它基于 Vitess 构建，提供数据库分支、非阻塞模式更改和自动备份。在本指南中，您将学习如何将 Prisma ORM 添加到现有 TypeScript 项目中，将其连接到 PlanetScale MySQL，内省现有数据库模式，并开始使用类型安全的 Prisma Client 进行查询。

注意

PlanetScale 还提供 PostgreSQL 数据库。如果您使用的是 PlanetScale PostgreSQL，请改为遵循添加到现有 PostgreSQL 项目指南。

先决条件

您需要

• 您的机器上安装了 Node.js v20.19+、v22.12+ 或 v24.0+
• JavaScript 或 TypeScript 基础知识

1. 设置 Prisma ORM

导航到您现有的项目目录并安装所需的依赖项

npm install prisma @types/node --save-dev
npm install @prisma/client @prisma/adapter-planetscale undici dotenv

每个包的作用如下

• prisma - 用于运行 prisma init、prisma db pull 和 prisma generate 等命令的 Prisma CLI
• @prisma/client - 用于查询数据库的 Prisma Client 库
• @prisma/adapter-planetscale - 用于将 Prisma Client 连接到数据库的 PlanetScale 驱动程序适配器
• undici - PlanetScale 适配器所需的快速 HTTP/1.1 客户端
• dotenv - 从您的 .env 文件加载环境变量

2. 初始化 Prisma ORM

使用以下命令创建 Prisma Schema 文件来设置您的 Prisma ORM 项目

npx prisma init --datasource-provider mysql --output ../generated/prisma

此命令执行以下操作

• 创建一个 prisma/ 目录，其中包含一个 schema.prisma 文件，其中包含您的数据库连接配置
• 在根目录中创建一个 .env 文件用于环境变量
• 创建一个 prisma.config.ts 文件用于 Prisma 配置

生成的 prisma.config.ts 文件如下所示

prisma.config.ts

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
})

生成的 schema 使用带有自定义输出路径的 ESM 优先的 prisma-client 生成器

prisma/schema.prisma

generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}

datasource db {
  provider     = "mysql"
  relationMode = "prisma"
}

信息

PlanetScale 要求 relationMode = "prisma"，因为它不支持外键约束。

3. 连接您的数据库

使用您的 PlanetScale 连接 URL 更新 .env 文件

.env

DATABASE_URL="mysql://username:password@host.connect.psdb.cloud/mydb?sslaccept=strict"

您可以在 PlanetScale 仪表板中找到您的连接字符串。

4. 内省您的数据库

运行以下命令以内省您现有的数据库

npx prisma db pull

此命令读取 DATABASE_URL 环境变量，连接到您的数据库，并内省数据库模式。然后，它将数据库模式从 SQL 转换为您的 Prisma 模式中的数据模型。

内省后，您的 Prisma 模式将包含代表您现有数据库表的模型。

5. 生成 Prisma ORM 类型

根据您内省的模式生成 Prisma Client

npx prisma generate

这会在 generated/prisma 目录中创建一个根据您的数据库模式量身定制的类型安全的 Prisma Client。

6. 实例化 Prisma Client

创建一个实用文件来实例化 Prisma Client。您需要将 Prisma ORM 驱动程序适配器的实例传递给 PrismaClient 构造函数

lib/prisma.ts

import "dotenv/config";
import { PrismaPlanetScale } from '@prisma/adapter-planetscale'
import { PrismaClient } from '../generated/prisma/client'
import { fetch as undiciFetch } from 'undici'

const adapter = new PrismaPlanetScale({ url: process.env.DATABASE_URL, fetch: undiciFetch })
const prisma = new PrismaClient({ adapter })

export { prisma }

7. 查询您的数据库

现在您可以使用 Prisma Client 查询您的数据库。创建一个 script.ts 文件

script.ts

import { prisma } from './lib/prisma'

async function main() {
  // Example: Fetch all records from a table
  // Replace 'user' with your actual model name
  const allUsers = await prisma.user.findMany()
  console.log('All users:', JSON.stringify(allUsers, null, 2))
}

main()
  .then(async () => {
    await prisma.$disconnect()
  })
  .catch(async (e) => {
    console.error(e)
    await prisma.$disconnect()
    process.exit(1)
  })

运行脚本

npx tsx script.ts

8. 演进您的模式

PlanetScale 使用分支工作流而非传统迁移。要更改您的数据库模式：

8.1. 更新您的 Prisma 模式文件

更新您的 Prisma 模式文件以反映您想要对数据库模式进行的更改。例如，添加一个新模型

prisma/schema.prisma

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  authorId  Int
  author    User     @relation(fields: [authorId], references: [id])
}

model User {
  id    Int    @id @default(autoincrement())
  email String @unique
  name  String?
  posts Post[]
}

8.2. 将更改推送到您的开发分支：

npx prisma db push

此命令将

• 将模式更改应用到您的 PlanetScale 数据库
• 重新生成 Prisma Client

信息

对于生产部署，请使用 PlanetScale 的分支工作流 来创建部署请求。

9. 使用 Prisma Studio 探索您的数据

Prisma Studio 是一个用于数据库的可视化编辑器。使用以下命令启动它

npx prisma studio --config ./prisma.config.ts

这会打开一个 Web 界面，您可以在其中查看和编辑数据。

支持的数据库

Prisma Studio 目前支持 PostgreSQL、MySQL 和 SQLite。有关更多详细信息，请参阅Prisma Studio 支持的数据库。

后续步骤

您已成功设置 Prisma ORM。接下来您可以探索

• 了解有关 Prisma Client 的更多信息：探索 Prisma Client API 以进行高级查询、筛选和关系操作
• 数据库迁移：了解 Prisma Migrate 以演进您的数据库模式
• 性能优化：发现查询优化技术
• 构建完整的应用程序：查看我们的框架指南，将 Prisma ORM 与 Next.js、Express 等集成
• 加入社区：在 Discord 上与其他开发者联系

更多信息

• PlanetScale 数据库连接器
• Prisma 配置参考
• 数据库内省
• PlanetScale 分支工作流