Prisma ORM 和 PlanetScale 快速入门

PlanetScale 是一个无服务器数据库平台。本指南涵盖 PlanetScale MySQL。在本指南中，您将学习如何从头开始设置一个新的 TypeScript 项目，使用 Prisma ORM 将其连接到 PlanetScale MySQL，并生成一个 Prisma 客户端以便轻松、类型安全地访问您的数据库。

注意

PlanetScale 还提供 PostgreSQL 数据库。如果您使用的是 PlanetScale PostgreSQL，请改为遵循 PostgreSQL 快速入门指南。

先决条件

您需要

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

您还需要

• 一个 PlanetScale 数据库
• 来自 PlanetScale 的数据库连接字符串

1. 创建新项目

创建一个项目目录并进入该目录

mkdir hello-prisma
cd hello-prisma

初始化一个 TypeScript 项目

npm init -y
npm install typescript tsx @types/node --save-dev
npx tsc --init

2. 安装所需的依赖项

安装本快速入门所需的软件包

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

每个包的作用如下

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

3. 配置 ESM 支持

更新 tsconfig.json 以兼容 ESM

tsconfig.json

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "node",
    "target": "ES2023",
    "strict": true,
    "esModuleInterop": true,
    "ignoreDeprecations": "6.0"
  }
}

更新 package.json 以启用 ESM

package.json

{
  "type": "module",
}

4. 初始化 Prisma ORM

现在，您可以通过在 Prisma CLI 前面加上 npx 来调用它

npx prisma

接下来，使用以下命令创建 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"
}

更新您的 schema 以包含 relationMode = "prisma" 用于 PlanetScale

prisma/schema.prisma

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

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

使用您的 PlanetScale 连接字符串更新您的 .env 文件

.env

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

替换为您的数据库仪表板中实际的 PlanetScale 连接字符串。

5. 定义您的数据模型

打开 prisma/schema.prisma 并添加以下模型

prisma/schema.prisma

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

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

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

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

  @@index([authorId])
}

注意

请注意 Post 模型上的 @@index([authorId])。当使用 relationMode = "prisma" 时，PlanetScale 要求对外键进行索引。

6. 将您的 schema 推送到 PlanetScale

PlanetScale 使用分支工作流而非传统的迁移。直接推送您的 schema

npx prisma db push

此命令根据您的模式创建数据库表。

现在运行以下命令生成 Prisma Client

npx prisma generate

7. 实例化 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 }

8. 编写您的第一个查询

创建一个 script.ts 文件来测试您的设置

script.ts

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

async function main() {
  // Create a new user with a post
  const user = await prisma.user.create({
    data: {
      name: 'Alice',
      email: 'alice@prisma.io',
      posts: {
        create: {
          title: 'Hello World',
          content: 'This is my first post!',
          published: true,
        },
      },
    },
    include: {
      posts: true,
    },
  })
  console.log('Created user:', user)

  // Fetch all users with their posts
  const allUsers = await prisma.user.findMany({
    include: {
      posts: true,
    },
  })
  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

您应该会在控制台中看到创建的用户和所有用户！

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 配置参考
• 数据库连接管理