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 模式语言对您的数据库建模
• 在您的模式中使用 Prisma ORM 现有的 sqlite 数据库连接器
• 在您的应用程序中使用 Prisma Client 与 D1 上的数据库服务器通信

需要考虑的差异

D1 和 SQLite 之间存在一些需要考虑的差异。在决定使用 D1 和 Prisma ORM 时，您应该注意以下事项

• **本地和远程 D1 (SQLite) 数据库**。Cloudflare 提供了 D1 的本地和远程版本。 本地版本使用 wrangler d1 CLI 的 --local 选项进行管理，并位于 .wrangler/state 中。 远程版本由 Cloudflare 管理，并通过 HTTP 访问。
• **进行模式更改**。由于 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 命令使用此迁移系统在您的文件系统上创建和管理迁移文件。

但是，此命令并不能帮助您确定用于创建数据库模式的 SQL 语句，这些语句需要放在这些迁移文件 *内部*。如果您想使用 Prisma Client 查询您的数据库，那么您的数据库模式必须映射到您的 Prisma 模式，因此建议从您的 Prisma 模式生成 SQL 语句。

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

创建初始迁移

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

1. 更新您的 Prisma 数据模型

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

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 命令，该命令比较两个 *模式*（通过其 --to-X 和 --from-X 选项）并生成从一个模式“演变”到另一个模式所需的步骤。这些模式可以是 Prisma 模式或 SQL 模式。

对于初始迁移，您可以使用特殊的 --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 语句的源是空模式。
• --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

使用后续迁移演进您的模式

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

1. 更新您的 Prisma 数据模型

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

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来指定源模式

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