使用 Prisma ORM 和 Cloudflare D1 在边缘构建应用（预览版）

使用 D1 将您的数据库带到边缘

边缘函数（例如 Cloudflare Workers）是一种轻量级的无服务器计算形式，在全球范围内进行分发。它们允许您将应用程序尽可能地部署和运行在靠近最终用户的位置。

D1 是 Cloudflare 面向边缘环境的原生无服务器数据库。它基于 SQLite，可在使用 Cloudflare 部署应用程序时使用。D1 于 2022 年首次推出。

遵循 Cloudflare 的地理分布式原则，将计算和数据更接近应用用户，D1 支持自动读副本：它根据数据库接收的查询数量及来源位置，动态管理数据库实例和只读副本的数量和位置。

这意味着读查询会在最接近发出查询位置的 D1 实例上执行。

虽然您也可以使用 Prisma ORM 与其他数据库提供商一起使用读副本，但这通常需要您使用 Read Replica Client 扩展。使用 D1 时，读副本是开箱即用的，无需专门的 Client 扩展。

另一方面，对于写操作，查询仍然会发送到单个主实例，以便将更改传播到所有读副本并确保数据一致性。

Prisma ORM 现在支持 D1 🚀 （预览版）

在 Prisma，我们相信 Cloudflare 走在未来应用构建和部署方式的最前沿。

您可以在这篇博客文章中了解更多关于我们如何将 Cloudflare 视为改进 Data DX 的合作伙伴：重塑开发者体验：Prisma 与 Cloudflare 引领 Data DX 之路

支持 D1 一直是 Prisma ORM 在 GitHub 上最受欢迎的功能请求之一。

作为 Cloudflare 技术的坚定支持者，我们很高兴地宣布，您现在可以在 Cloudflare Workers（和 Pages）内部使用 Prisma ORM 访问 D1 数据库。

请注意，此功能基于目前处于预览版的驱动适配器（driver adapters），因此我们也认为对 D1 的支持处于预览版。您需要通过 generator 块上的 previewFeatures 字段显式启用它。

Prisma ORM 与 D1 入门

接下来，您将找到从头开始设置和部署使用 Prisma ORM 访问 D1 数据库的 Cloudflare Worker 的分步说明。

截至此版本，Prisma Migrate 尚未完全兼容 D1。在本教程中，您将结合使用 D1 的迁移系统和 prisma migrate diff 命令来生成和运行迁移。

先决条件

• 您的机器上安装了 Node.js 和 npm
• 一个 Cloudflare 账户

1. 创建 Cloudflare Worker

第一步，使用 npm create 来引导一个纯净的 Cloudflare Worker 版本（使用 Cloudflare 的 hello-world 模板）。在终端中运行以下命令

这将启动一个 CLI 向导。在每次出现问题时，通过按 Return 键选择所有默认选项。

向导结束后，您应该拥有一个已部署的 Cloudflare Worker，其域名为 https://prisma-d1-example.USERNAME.workers.dev，该 Worker 只是在浏览器中渲染 "Hello World"

2. 初始化 Prisma ORM

Worker 已就位，现在我们来设置 Prisma ORM。

首先，进入项目目录并安装 Prisma CLI

接下来，安装 Prisma Client 包以及适用于 D1 的驱动适配器

最后，使用以下命令引导 Prisma ORM 所需的文件

此命令执行了两项操作

• 它创建了一个名为 prisma 的新目录，其中包含您的 Prisma schema 文件。
• 它创建了一个 .env 文件，该文件通常用于配置 Prisma CLI 将读取的环境变量。

在本教程中，您不需要 .env 文件，因为 Prisma ORM 和 D1 之间的连接将通过一个绑定（binding）发生。您将在下一步找到设置此绑定的说明。

由于您将使用目前处于预览版的驱动适配器功能，因此需要通过 generator 块上的 previewFeatures 字段显式启用它。

打开您的 schema.prisma 文件，并将 generator 块调整如下

3. 创建 D1 数据库

在此步骤中，您将设置 D1 数据库。通常有两种方法：使用 Cloudflare Dashboard UI 或通过 wrangler CLI。在本教程中，您将使用 CLI。

打开终端并运行以下命令

如果一切顺利，您应该会看到类似以下的输出

您现在已在 Cloudflare 账户中拥有一个 D1 数据库，并与您的 Cloudflare Worker 进行了绑定。

复制命令输出的最后一部分，并将其粘贴到您的 wrangler.toml 文件中。它应该看起来像这样

请注意，上面代码片段中的 __YOUR_D1_DATABASE_ID__ 是一个占位符，应替换为您自己的 D1 实例的数据库 ID。如果您未能从终端输出中获取此 ID，也可以在 Cloudflare Dashboard 中找到它，或者在终端中运行 npx wrangler d1 info prisma-demo-db 命令。

接下来，您将在数据库中创建一个数据表，以便能够使用 Prisma ORM 向 D1 发送一些查询。

4. 在数据库中创建表

D1 通过 wrangler d1 migrate 命令拥有自己的迁移系统（migration system）。此迁移系统与 Prisma CLI 配合良好，Prisma CLI 提供了用于生成 schema 更改 SQL 语句的工具。因此您可以

• 使用 D1 的原生迁移系统创建并将迁移文件应用到您的 D1 实例
• 使用 Prisma CLI 生成任何 schema 更改的 SQL 语句

接下来，您将同时使用 D1 的迁移系统和 Prisma CLI 创建并运行针对数据库的迁移。

首先，使用 wrangler CLI 创建新的迁移

当提示命令是否可以创建一个名为 migrations 的新文件夹时，按 Return 键确认。

该命令现在创建了一个名为 migrations 的新目录，并在其中创建了一个名为 0001_create_user_table.sql 的空文件。

接下来，您需要将创建 User 表的 SQL 语句添加到该文件中。打开 schema.prisma 文件，并添加以下 User 模型

现在，在终端中运行以下命令，生成一个与上面 User 模型等效的创建 User 表的 SQL 语句

这会将创建新 User 表的 SQL 语句存储在之前的迁移文件 migrations/0001_ceate_user_table.sql 中，它看起来像这样

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

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

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

首先，对您的本地数据库执行 schema 更改

接下来，对远程数据库执行

当提示您确认是否应用迁移时，两次都按 Return 键。

现在，您的本地和远程 D1 实例都包含 User 表。

我们也来创建一些可供 Worker 运行时查询的模拟数据。这次，您将在不将其存储到文件中的情况下运行 SQL 语句。

再次，首先对您的本地数据库运行命令

最后，对您的远程数据库运行

现在，您的本地和远程数据库实例中都有一个模拟记录。您可以在 .wrangler/state 中找到本地 SQLite 文件，而可以在 Cloudflare Dashboard 中检查远程文件。

5. 从 Worker 查询数据库

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

1. 将 DB 添加到 Env interface 中。
2. 使用 PrismaD1 驱动适配器实例化 PrismaClient。
3. 使用 Prisma Client 发送查询并返回结果。

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

在运行 Worker 之前，您需要使用以下命令生成 Prisma Client

6. 在本地运行 Worker

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

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

7. 部署 Worker

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

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

恭喜您，您刚刚部署了一个使用 D1 作为数据库并通过 Prisma ORM 查询它的 Cloudflare Worker 🎉

立即试用

我们很想听听您对 Prisma ORM 新增 D1 支持的看法！请务必尝试并前往 GitHub 或 Discord 与我们分享您的反馈。编码愉快 ✌️