跳至主要内容

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 Workers 的应用程序。

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

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

与其他数据库提供商的共同点​

D1 基于 SQLite。

将 Prisma ORM 与 D1 一起使用的许多方面都与将 Prisma ORM 与任何其他关系型数据库一起使用类似。您仍然可以

需要考虑的差异​

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

  • 进行 schema 更改。对于 Prisma ORM 7，您需要使用 D1 的 迁移系统，通过 Wrangler CLI 结合 prisma migrate diff 命令进行迁移工作流。有关更多信息，请参阅下面的使用 Prisma ORM 在 D1 上进行 schema 迁移部分。
  • 本地和远程 D1 (SQLite) 数据库。Cloudflare 提供了 D1 的本地和远程版本。本地版本使用 wrangler d1 CLI 的 --local 选项进行管理，位于 .wrangler/state。 远程版本由 Cloudflare 管理，通过 HTTP 访问。

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

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

如果您想使用 D1 和 Prisma ORM 部署 Cloudflare Worker，请遵循这些分步说明。

使用 Prisma ORM 在 D1 上进行 schema 迁移​

对于 Prisma ORM 7，管理 Cloudflare D1 数据库 schema 迁移的推荐方法是使用 Wrangler CLI 结合 prisma migrate diff。

使用 Wrangler CLI 与 prisma migrate diff​

Cloudflare D1 带有自己的迁移系统，通过 wrangler d1 CLI 命令工作。

Wrangler CLI 提供了迁移的结构，但您需要从 Prisma schema 生成 SQL 语句。这就是 prisma migrate diff 的作用——它根据您的 Prisma schema 生成 SQL 语句，然后您可以使用 Wrangler 应用这些语句。

创建初始迁移​

创建初始迁移的工作流如下所示。假设您有一个没有任何表的全新 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 命令，它比较两个 schemas（通过其 --to-X 和 --from-X 选项）并生成从一个 schema “演变”到另一个 schema 所需的步骤。这些 schema 可以是 Prisma 或 SQL schema。

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

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

上面的命令使用以下选项

  • --from-empty：SQL 语句的源是一个空 schema。
  • --to-schema ./prisma/schema.prisma：SQL 语句的目标是 ./prisma/schema.prisma 中的 schema。
  • --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-empty，而是需要使用 --from-local-d1，因为此时 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 ./prisma/schema.prisma \
  --script \
  --output migrations/0002_create_post_table.sql

上面的命令使用以下选项

  • --from-local-d1：SQL 语句的源是本地 D1 数据库文件。
  • --to-schema ./prisma/schema.prisma：SQL 语句的目标是 ./prisma/schema.prisma 中的 schema。
  • --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

限制​

不支持事务​

Cloudflare D1 目前不支持事务（请参阅开放的功能请求）。因此，Prisma ORM 不支持 Cloudflare D1 的事务。当使用 Prisma 的 D1 适配器时，隐式和显式事务将被忽略并作为单独的查询运行，这会破坏事务 ACID 属性的保证。

打开方式
复制为 Markdown
在 Claude 中打开
在 ChatGPT 中打开
在 T3.chat 中打开
在 GitHub 中编辑
© . This site is unofficial and not affiliated with Prisma Data, Inc.