跳转至主要内容

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

10 分钟

简介​

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

先决条件​

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

  • 一个 Cloudflare 帐户
  • 已安装 Node.js（版本 16 或更高版本）
  • 已安装 Wrangler CLI（版本 3.39.0 或更高版本）
  • 基本熟悉 Cloudflare Workers 和 D1

1. 配置 Prisma schema​

在您的 Prisma schema 中，将 driverAdapters Preview 功能添加到 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 Dashboard 中找到它，或者在终端中运行 npx wrangler d1 list 和 npx wrangler d1 info __YOUR_D1_DATABASE_NAME__。

4. 设置数据库迁移​

使用 D1 的迁移系统创建并应用迁移

# Create migration directory and file
npx wrangler d1 migrations create __YOUR_D1_DATABASE_NAME__ create_user_table

再次将 __YOUR_D1_DATABASE_NAME__ 替换为您的数据库名称，并在提示时确认您要创建 migrations 目录。运行此命令后，应该会有一个名为 migrations 的新文件夹，其中包含一个名为 0001_create_user_table.sql 的文件。

您现在可以生成创建 User 表所需的 SQL 语句，该表可以映射到您的 Prisma schema 中的 User 模型，如下所示

# Generate SQL using Prisma Migrate
npx prisma migrate diff --from-empty --to-schema-datamodel ./prisma/schema.prisma --script --output migrations/0001_create_user_table.sql

请注意，生成的 SQL 语句存储在 migrations 目录下的一个名为 0001_create_user_table.sql 的文件中，该文件如下所示

migrations/0001_create_user_table.sql
-- CreateTable
CREATE TABLE "User" (
    "id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
    "email" TEXT NOT NULL,
    "name" TEXT
);

-- CreateIndex
CREATE UNIQUE INDEX "User_email_key" ON "User"("email");

您现在需要使用 wrangler d1 migrations apply 命令将此 SQL 语句发送到 D1。请注意，此命令接受两个选项

  • --local：针对 D1 的本地版本执行语句。D1 的此本地版本是一个 SQLite 数据库文件，它将位于您的项目中。当您想在本地机器上开发和测试 Worker 时，此方法非常有用。在 Cloudflare 文档 中了解更多信息。
  • --remote：针对 D1 的远程版本执行语句。此版本由您已部署的 Cloudflare Workers 使用。在 Cloudflare 文档 中了解更多信息。

在本教程中，您将同时执行这两项操作：在本地测试 Worker 并在之后部署它。因此，您需要运行以下两个命令。打开您的终端并粘贴以下命令

# For the local database
npx wrangler d1 migrations apply __YOUR_D1_DATABASE_NAME__ --local

# For the remote database
npx wrangler d1 migrations apply __YOUR_D1_DATABASE_NAME__ --remote

和之前一样，您需要将 __YOUR_D1_DATABASE_NAME__ 替换为您的 D1 数据库的名称。

让我们也创建一些虚拟数据，以便在 Worker 运行时可以查询。这次，您将运行 SQL 语句，而无需将其存储在文件中

# For the local database
npx wrangler d1 execute __YOUR_D1_DATABASE_NAME__ --command "INSERT INTO  \"User\" (\"email\", \"name\") VALUES
('[email protected]', 'Jane Doe (Local)');" --local

# For the remote database
npx wrangler d1 execute __YOUR_D1_DATABASE_NAME__ --command "INSERT INTO  \"User\" (\"email\", \"name\") VALUES
('[email protected]', 'Jane Doe (Remote)');" --remote

5. 实现 Worker​

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

npx prisma generate

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

  1. 将 DB 绑定添加到 Env 接口。（或者，您可以运行 npx wrangler types 以从名为 worker-configuration.d.ts 的单独文件中从绑定生成 Env 类型。）
  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

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

;[{ id: 1, email: '[email protected]', name: 'Jane Doe (Local)' }]

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

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

npm run deploy

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

;[{ id: 1, email: '[email protected]', name: 'Jane Doe (Remote)' }]

下一步​

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

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

更多信息和更新