跳至主要内容

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 与任何其他关系型数据库类似。您仍然可以

需要考虑的差异​

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 客户端查询数据库，那么您的数据库模式必须映射到您的 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