使用 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 视为改进 数据 DX 的合作伙伴：重新定义开发者体验：Prisma 和 Cloudflare 引领数据 DX

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

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

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

Prisma ORM 和 D1 入门

接下来，您将找到从头开始设置和部署一个 Cloudflare Worker 的分步说明，该 Worker 带有通过 Prisma ORM 完全访问的 D1 数据库。

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

先决条件

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

1. 创建 Cloudflare Worker

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

这将弹出一个 CLI 向导。每次出现问题时，按 回车 键选择所有 默认 选项。

在向导结束时，您应该在域 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 配合得很好，后者提供了允许您为模式更改生成 SQL 语句的工具。因此您可以

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

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

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

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

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

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

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

这会将一个 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 并 之后部署它。因此，您需要运行这两个命令。打开您的终端并粘贴以下命令。

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

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

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

现在您的本地和远程 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://:8787 查看数据库查询结果

7. 部署 Worker

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

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

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

立即试用

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