使用 Prisma ORM 和 Cloudflare D1 (预览版) 在边缘构建应用程序

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

边缘函数，例如 Cloudflare Workers，是一种轻量级无服务器计算形式，分布于全球各地。 它们允许您尽可能靠近最终用户部署和运行您的应用程序。

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

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

这意味着读取查询是针对最靠近发出查询位置的 D1 实例执行的。

虽然您也可以将读取副本与 Prisma ORM 一起用于其他数据库提供商，但这通常需要您使用 读取副本客户端扩展。 使用 D1 时，开箱即支持读取副本，无需专用客户端扩展。

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

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

在 Prisma，我们相信 Cloudflare 正处于构建应用程序构建和部署方式的未来前沿。

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

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

作为 Cloudflare 技术提供商的坚定拥护者，我们很高兴地分享，您现在可以在 Cloudflare Workers（和 Pages）中使用 Prisma ORM 来访问 D1 数据库。

请注意，此功能基于目前处于预览版的 驱动程序适配器，因此我们也认为 D1 支持也处于预览版。

Prisma ORM 和 D1 入门

在下文中，您将找到从头开始设置和部署 Cloudflare Worker 以及通过 Prisma ORM 访问的 D1 数据库的分步说明。

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

先决条件

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

1. 创建 Cloudflare Worker

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

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

在向导结束时，您应该拥有一个部署在域 https://prisma-d1-example.USERNAME.workers.dev 的 Cloudflare Worker，它只是在浏览器中呈现“Hello World”

2. 初始化 Prisma ORM

Worker 就位后，让我们继续设置 Prisma ORM。

首先，导航到项目目录并安装 Prisma CLI

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

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

此命令执行了两个操作

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

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

由于您将使用当前处于预览版的驱动程序适配器功能，因此您需要通过 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 命令附带了自己的 迁移系统。 此迁移系统与 Prisma CLI 配合良好，Prisma CLI 提供了允许您为模式更改生成 SQL 语句的工具。 因此您可以

• 使用 D1 的原生迁移系统来创建迁移文件并将其应用于您的 D1 实例
• 使用 Prisma CLI 为任何模式更改生成 SQL 语句

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

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

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

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

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

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

这会将 SQL 语句存储到您的迁移文件 migrations/0001_ceate_user_table.sql 中，以创建新的 User 表，以下是它的外观

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

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

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

首先，针对您的本地数据库执行模式更改

接下来，针对远程数据库

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

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

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

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

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

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

5. 从 Worker 查询您的数据库

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

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

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

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

6. 在本地运行 Worker

数据库查询就位并且 Prisma Client 生成后，您可以继续在本地运行 Worker

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

7. 部署 Worker

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

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

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

立即试用

我们很想听听您对 Prisma ORM 中新的 D1 支持的看法！ 请试用它并在 GitHub 或 Discord 上与我们分享您的反馈。 祝您编码愉快 ✌️