Cloudflare D1

本指南讨论了使用 Prisma ORM 和 Cloudflare D1 背后的概念，解释了 Cloudflare D1 和其他数据库提供商之间的共性和差异，并引导您完成配置应用程序以与 Cloudflare D1 集成的过程。

Prisma ORM 对 Cloudflare D1 的支持目前处于 预览 阶段。我们欢迎您在 GitHub 上提供反馈。

如果您想使用 D1 和 Prisma ORM 部署 Cloudflare Worker，请按照本教程操作。

什么是 Cloudflare D1？

D1 是 Cloudflare 的原生无服务器数据库，最初于 2022 年推出。它基于 SQLite，可在使用 Cloudflare 部署应用程序时使用。

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

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

与其他数据库提供商的共性

D1 基于 SQLite。

将 Prisma ORM 与 D1 结合使用的许多方面与将 Prisma ORM 与任何其他关系数据库结合使用非常相似。您仍然可以

• 使用 Prisma Schema Language 对数据库进行建模
• 在您的 schema 中使用 Prisma ORM 现有的 sqlite 数据库连接器
• 在您的应用程序中使用 Prisma Client 与 D1 的数据库服务器通信

需要考虑的差异

D1 和 SQLite 之间存在许多需要考虑的差异。当您决定使用 D1 和 Prisma ORM 时，您应该注意以下几点

• 本地和远程 D1 (SQLite) 数据库。Cloudflare 提供 D1 的本地和远程版本。本地 版本使用 wrangler d1 CLI 的 --local 选项进行管理，位于 .wrangler/state 中。远程 版本由 Cloudflare 管理，并通过 HTTP 访问。
• 进行 schema 更改。由于 D1 使用 HTTP 连接到远程数据库，这使其与 Prisma Migrate 的某些命令（例如 prisma migrate dev）不兼容。但是，您可以将 D1 的 迁移系统 和 prisma migrate diff 命令用于您的迁移工作流程。有关更多信息，请参阅下面的迁移工作流程。

如何在 Cloudflare Workers 或 Cloudflare Pages 中连接到 D1

将 Prisma ORM 与 D1 结合使用时，您需要使用 sqlite 数据库提供程序和 @prisma/adapter-d1 驱动程序适配器。

如果您想使用 D1 和 Prisma ORM 部署 Cloudflare Worker，请按照这些分步说明操作。

迁移工作流程

Cloudflare D1 自带 迁移系统。我们建议您通过 wrangler d1 migrations 命令使用此迁移系统，以在您的文件系统中创建和管理迁移文件。

但是，此命令无法帮助您找出用于创建数据库 schema 的 SQL 语句，这些语句需要放入这些迁移文件内部。如果您想使用 Prisma Client 查询数据库，则数据库 schema 映射到您的 Prisma schema 非常重要，这就是为什么建议从您的 Prisma schema 生成 SQL 语句的原因。

使用 D1 时，您可以为此目的使用 prisma migrate diff 命令。

创建初始迁移

创建初始迁移的工作流程如下所示。假设您有一个没有任何表的新 D1 实例。

1. 更新您的 Prisma 数据模型

这是您要映射到 D1 实例的 Prisma schema 的初始版本

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
}

2. 使用 wrangler CLI 创建迁移文件

接下来，您需要使用 wrangler d1 migrations create 命令创建迁移文件

npx wrangler d1 migrations create __YOUR_DATABASE_NAME__ create_user_table

由于这是第一次迁移，因此该命令将提示您也创建一个 migrations 文件夹。请注意，如果您希望将迁移文件存储在其他位置，您可以使用 Wrangler 自定义它。

一旦命令执行完毕，并且假设您已为迁移文件的位置选择了默认的 migrations 名称，则该命令已为您创建了以下文件夹和文件

migrations/
└── 0001_create_user_table.sql

但是，在将迁移应用于 D1 实例之前，您实际上需要将 SQL 语句放入当前为空的 0001_create_user_table.sql 文件中。

3. 使用 prisma migrate diff 生成 SQL 语句

要生成初始 SQL 语句，您可以使用 prisma migrate diff 命令，该命令比较两个schema（通过其 --to-X 和 --from-X 选项），并生成从一个 schema“演变”到另一个 schema 所需的步骤。这些 schema 可以是 Prisma schema 或 SQL schema。

对于初始迁移，您可以使用特殊的 --from-empty 选项

npx prisma migrate diff \
  --from-empty \
  --to-schema-datamodel ./prisma/schema.prisma \
  --script \
  --output migrations/0001_create_user_table.sql

上面的命令使用以下选项

• --from-empty：SQL 语句的来源是空 schema。
• --to-schema-datamodel ./prisma/schema.prisma：SQL 语句的目标是 ./prisma/schema.prisma 中的数据模型。
• --script：将结果输出为 SQL。如果您省略此选项，“迁移步骤”将以纯英文生成。
• --output migrations/0001_create_user_table.sql：将结果存储在 migrations/0001_create_user_table.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");

4. 使用 wrangler d1 migrations apply 执行迁移

最后，您可以针对您的 D1 实例应用迁移。

对于本地实例，运行

npx wrangler d1 migrations apply __YOUR_DATABASE_NAME__ --local

对于远程实例，运行

npx wrangler d1 migrations apply __YOUR_DATABASE_NAME__ --remote

使用进一步的迁移来演变您的 schema

对于任何进一步的迁移，您可以使用相同的工作流程，但您需要使用 --from-local-d1 而不是 --from-empty，因为 prisma migrate diff 命令的源 schema 现在是该本地 D1 实例的当前 schema，而目标仍然是您（然后更新）的 Prisma schema。

1. 更新您的 Prisma 数据模型

假设您已使用另一个模型更新了您的 Prisma schema

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

model Post {
  id       Int    @id @default(autoincrement())
  title    String
  author   User   @relation(fields: [authorId], references: [id])
  authorId Int
}

2. 使用 wrangler CLI 创建迁移文件

和以前一样，您首先需要创建迁移文件

npx wrangler d1 migrations create __YOUR_DATABASE_NAME__ create_post_table

一旦命令执行完毕（再次假设您已为迁移文件的位置选择了默认的 migrations 名称），该命令已在 migrations 文件夹内创建了一个新文件

migrations/
├── 0001_create_user_table.sql
└── 0002_create_post_table.sql

和以前一样，您现在需要将 SQL 语句放入当前为空的 0002_create_post_table.sql 文件中。

3. 使用 prisma migrate diff 生成 SQL 语句

如上所述，您现在需要使用 --from-local-d1 而不是 --from-empty 来指定源 schema

npx prisma migrate diff \
  --from-local-d1 \
  --to-schema-datamodel ./prisma/schema.prisma \
  --script \
  --output migrations/0002_create_post_table.sql

上面的命令使用以下选项

• --from-local-d1：SQL 语句的来源是本地 D1 数据库文件。
• --to-schema-datamodel ./prisma/schema.prisma：SQL 语句的目标是 ./prisma/schema.prisma 中的数据模型。
• --script：将结果输出为 SQL。如果您省略此选项，“迁移步骤”将以纯英文生成。
• --output migrations/0002_create_post_table.sql：将结果存储在 migrations/0002_create_post_table.sql 中。

运行此命令后，migrations/0002_create_post_table.sql 将具有以下内容

migrations/0002_create_post_table.sql

-- CreateTable
CREATE TABLE "Post" (
    "id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
    "title" TEXT NOT NULL,
    "authorId" INTEGER NOT NULL,
    CONSTRAINT "Post_authorId_fkey" FOREIGN KEY ("authorId") REFERENCES "User" ("id") ON DELETE RESTRICT ON UPDATE CASCADE
);

4. 使用 wrangler d1 migrations apply 执行迁移

最后，您可以针对您的 D1 实例应用迁移。

对于本地实例，运行

npx wrangler d1 migrations apply __YOUR_DATABASE_NAME__ --local

对于远程实例，运行

npx wrangler d1 migrations apply __YOUR_DATABASE_NAME__ --remote