跳到主要内容

如何在 Cloudflare D1 中使用 Prisma ORM

10 分钟

简介​

本指南将向您展示如何在 Cloudflare D1（一个在 Cloudflare 边缘网络上运行的无服务器 SQL 数据库）中使用 Prisma ORM。您将学习如何使用 D1 设置 Prisma ORM、处理迁移以及将应用程序部署到 Cloudflare Workers。您可以在 GitHub 上找到一个部署就绪的示例。

先决条件​

在开始本指南之前，请确保您已具备：

  • 一个 Cloudflare 账户
  • 已安装 Node.js（版本 18 或更高）
  • 已安装 Wrangler CLI（版本 3.39.0 或更高）
  • 对 Cloudflare Workers 和 D1 有基本了解

1. 配置 Prisma schema​

在您的 Prisma schema 中，将 driverAdapters 预览功能添加到 generator 块中，并将 datasource 的 provider 设置为 sqlite。如果您刚刚使用 prisma init 启动了 Prisma schema，请务必添加以下 User 模型：

schema.prisma
generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

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

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

2. 安装依赖项​

接下来，安装所需的软件包：

npm install @prisma/adapter-d1

此外，请务必使用 wrangler@^3.39.0 以上版本的 Wrangler CLI，否则下一节中使用的 --remote 标志将不可用。

3. 设置 D1 数据库连接​

要将您的 Workers 连接到 D1 实例，请将以下绑定添加到您的 wrangler.toml：

wrangler.toml
name = "prisma-cloudflare-worker-example"
main = "src/index.ts"
compatibility_date = "2024-03-20"
compatibility_flags = ["nodejs_compat"]

[[d1_databases]]
binding = "DB" # i.e. available in your Worker on env.DB
database_name = "__YOUR_D1_DATABASE_NAME__" # to be replaced
database_id = "__YOUR_D1_DATABASE_ID__"     # to be replaced

请注意，上面代码片段中的 __YOUR_D1_DATABASE_NAME__ 和 __YOUR_D1_DATABASE_ID__ 是占位符，应替换为您自己的 D1 实例的数据库名称和 ID。

如果您未能从终端输出中获取此 ID，您也可以在 Cloudflare 控制面板中找到它，或者在终端中运行 npx wrangler d1 list 和 npx wrangler d1 info __YOUR_D1_DATABASE_NAME__。

4. 设置数据库迁移​

注意

我们建议使用 prisma migrate 来保持 D1 中的数据迁移。但是，如果您更喜欢使用 Cloudflare 的迁移系统，该工作流也可用

4.1 添加所需的环境变量​

为了使用 Prisma D1 适配器，您需要向 .env 文件添加一些密钥：

  • DATABASE_URL：您的本地 D1 实例的路径。通常是 "file:./prisma/db.sqlite"。
  • CLOUDFLARE_ACCOUNT_ID：您的 Cloudflare 账户 ID，通过 npx wrangler whoami 获取。
  • CLOUDFLARE_DATABASE_ID：您的数据库 ID，在D1 数据库创建期间检索。
  • CLOUDFLARE_D1_TOKEN：此 API 令牌由 Prisma ORM 用于直接与您的 D1 实例通信。要创建此令牌，请按照以下步骤操作：
    1. 访问 https://dash.cloudflare.com/profile/api-tokens
    2. 点击“创建令牌”
    3. 点击“自定义令牌”模板
    4. 填写模板：确保使用易于识别的名称并添加 Account / D1 / Edit 权限。
    5. 点击“继续摘要”，然后点击“创建令牌”。

您现在可以存储这些密钥供 Prisma ORM 使用。我们建议使用 .env 文件进行本地开发，但任何密钥存储都可以。

.env
DATABASE_URL="file:./prisma/db.sqlite"

CLOUDFLARE_ACCOUNT_ID="0773..."
CLOUDFLARE_DATABASE_ID="01f30366-..."
CLOUDFLARE_D1_TOKEN="F8Cg..."

4.2 配置 Prisma Config​

确保您的项目根目录中有一个 prisma.config.ts 文件，并定义了迁移驱动适配器。

import path from 'node:path'
import type { PrismaConfig } from 'prisma'
import { PrismaD1HTTP } from '@prisma/adapter-d1'

// import your .env file
import 'dotenv/config'

type Env = {
  CLOUDFLARE_D1_TOKEN: string
  CLOUDFLARE_ACCOUNT_ID: string
  CLOUDFLARE_DATABASE_ID: string
}

export default {
  earlyAccess: true,
  schema: path.join('prisma', 'schema.prisma'),
  migrate: {
    async adapter(env) {
      return new PrismaD1HTTP({
        CLOUDFLARE_D1_TOKEN: env.CLOUDFLARE_D1_TOKEN,
        CLOUDFLARE_ACCOUNT_ID: env.CLOUDFLARE_ACCOUNT_ID,
        CLOUDFLARE_DATABASE_ID: env.CLOUDFLARE_DATABASE_ID,
      })
    },
  },
} satisfies PrismaConfig<Env>

这将允许 prisma migrate 与您的 D1 数据库交互。

4.3 运行您的第一次迁移​

您现在可以运行 prisma migrate dev 来迁移您的数据库以匹配您的本地 schema

npx prisma migrate dev --name init

我们再创建一些虚拟数据，以便在 Worker 运行后可以查询。这次，我们将使用 wrangler 运行 SQL 语句，而不将其存储在文件中：

# For the local database
npx wrangler d1 execute __YOUR_D1_DATABASE_NAME__ --command "INSERT INTO  \"User\" (\"email\", \"name\") VALUES
('jane@prisma.io', 'Jane Doe (Local)');" --local

# For the remote database
npx wrangler d1 execute __YOUR_D1_DATABASE_NAME__ --command "INSERT INTO  \"User\" (\"email\", \"name\") VALUES
('jane@prisma.io', 'Jane Doe (Remote)');" --remote

5. 实现 Worker​

在将 Prisma Client 查询添加到您的 Worker 之前，您需要使用以下命令生成 Prisma Client：

npx prisma generate

为了使用 Prisma ORM 从 Worker 查询您的数据库，您需要：

  1. 将 DB 绑定添加到 Env 接口。（或者，您可以运行 npx wrangler types 从绑定中生成 Env 类型，并将其存储在一个名为 worker-configuration.d.ts 的单独文件中。）
  2. 使用 PrismaD1 驱动适配器实例化 PrismaClient。
  3. 使用 Prisma Client 发送查询并返回结果。

打开 src/index.ts 并将其全部内容替换为以下内容：

src/index.ts
import { PrismaClient } from '@prisma/client'
import { PrismaD1 } from '@prisma/adapter-d1'

export interface Env {
  DB: D1Database
}

export default {
  async fetch(
    request: Request,
    env: Env,
    ctx: ExecutionContext
  ): Promise<Response> {
    const adapter = new PrismaD1(env.DB)
    const prisma = new PrismaClient({ adapter })

    const users = await prisma.user.findMany()
    const result = JSON.stringify(users)
    return new Response(result)
  },
}

6. 在本地运行 Worker​

数据库查询就绪，Prisma Client 也已生成，您现在可以运行 Worker 了：

npm run dev

现在您可以在浏览器中打开 http://localhost:8787 查看数据库查询结果

;[{ id: 1, email: 'jane@prisma.io', name: 'Jane Doe (Local)' }]

7. 设置 DATABASE_URL 环境变量并部署 Worker​

要部署 Worker，请运行以下命令：

npm run deploy

您部署的 Worker 可以通过 https://prisma-d1-example.USERNAME.workers.dev 访问。如果您在浏览器中导航到该 URL，您应该会看到从您的远程 D1 数据库查询到的以下数据：

;[{ id: 1, email: 'jane@prisma.io', name: 'Jane Doe (Remote)' }]

后续步骤​

现在您已经使用 Cloudflare D1 设置了 Prisma ORM，您可以：

  • 使用 Prisma 强大的查询 API 添加更复杂的查询
  • 设置 Prisma Studio 进行数据库管理
  • 实施数据库监控
  • 添加自动化测试

更多信息


与 Prisma 保持联系

通过以下方式与我们联系，继续您的 Prisma 之旅： 我们的活跃社区。保持了解、参与并与其他开发者协作。

我们真诚地重视您的参与，并期待您成为我们社区的一员！

© . All rights reserved.