如何将 Prisma ORM 与 Cloudflare D1 结合使用

10 分钟

简介

本指南将向您展示如何将 Prisma ORM 与 Cloudflare D1 结合使用，Cloudflare D1 是一个运行在 Cloudflare 边缘网络的无服务器 SQL 数据库。您将学习如何使用 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 CLI 版本高于 `wrangler@^3.39.0`，否则后续章节中使用的 `--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 Dashboard 中找到它，或者在终端中运行 `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'),
  migration: {
    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

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

npx prisma generate

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

将 `DB` 绑定添加到 `Env` 接口。（或者，您可以运行`npx wrangler types` 命令，将绑定生成到名为 `worker-configuration.d.ts` 的单独文件中，从而生成 `Env` 类型。）
使用 `PrismaD1` 驱动适配器实例化 `PrismaClient`。
使用 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)' }]

下一步

现在您已将 Prisma ORM 与 Cloudflare D1 结合设置完成，您可以

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

了解更多信息

与 Prisma 保持联系

通过以下方式连接，继续您的 Prisma 之旅我们活跃的社区。保持知情，参与其中，并与其他开发者协作

在 X 上关注我们获取公告、直播活动和实用技巧。
加入我们的 Discord 提问、与社区交流，并通过对话获得积极支持。
在 YouTube 上订阅获取教程、演示和直播。
在 GitHub 上参与通过加星标仓库、报告问题或贡献问题来参与。

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

简介​

先决条件​

1. 配置 Prisma Schema​

2. 安装依赖​

3. 设置 D1 数据库连接​

4. 设置数据库迁移​

4.1 添加所需的环境变量​

4.2 配置 Prisma Config​

4.3 运行首次迁移​

5. 实现 Worker​

6. 在本地运行 Worker​

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

下一步​