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 和任何其他關係型資料庫一樣。您仍然可以：

• 使用 Prisma Schema Language 對資料庫進行建模
• 在您的 schema 中使用 Prisma ORM 現有的 sqlite 資料庫聯結器
• 在您的應用程式中使用 Prisma Client 與 D1 的資料庫伺服器通訊

需要考慮的差異

D1 和 SQLite 之間存在許多差異，您在決定使用 D1 和 Prisma ORM 時應注意以下幾點：

• 進行 schema 更改。從 v6.6.0 起，並且使用 prisma.config.ts 檔案，您可以使用 prisma db push。但是，如果您更喜歡 Cloudflare 優先的方法，您可以使用 D1 的遷移系統和 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 遷移

您可以使用兩種方法來遷移您的資料庫 schema 與 Prisma ORM 和 D1：

• 透過 prisma.config.ts 中的驅動介面卡使用 prisma db push
• 使用 Wrangler CLI

透過 prisma.config.ts 中的驅動介面卡使用 Prisma Migrate（搶先體驗）

警告

此功能已在 搶先體驗階段的 v6.6.0 中引入，並支援以下命令：

• prisma db push
• prisma db pull
• prisma migrate diff

其他命令，如 prisma migrate dev 和 prisma migrate deploy 將很快新增。

1. 安裝 Prisma D1 驅動介面卡

在您的終端中執行此命令：

npm install @prisma/adapter-d1

2. 設定環境變數

為了設定 D1 介面卡，您需要向 .env 檔案新增一些金鑰：

• CLOUDFLARE_ACCOUNT_ID：您的 Cloudflare 賬戶 ID，透過 npx wrangler whoami 獲取。
• CLOUDFLARE_DATABASE_ID：在 D1 資料庫建立期間檢索。如果您有現有的 D1 資料庫，您可以使用 npx wrangler d1 list 和 npx wrangler d1 info 獲取 ID。
• CLOUDFLARE_D1_TOKEN：此 API 令牌用於 Prisma ORM 直接與您的 D1 例項通訊。要建立它，請遵循以下步驟：
  1. 訪問 https://dash.cloudflare.com/profile/api-tokens
  2. 點選 建立令牌
  3. 點選 自定義令牌 模板
  4. 填寫模板：確保您使用一個可識別的名稱，並新增 賬戶 / D1 / 編輯 許可權。
  5. 點選 繼續到摘要，然後點選 建立令牌。

然後您可以將這些新增到您的 .env 檔案中，或者如果它們儲存在不同的秘密儲存中，則直接使用它們。

.env

CLOUDFLARE_ACCOUNT_ID="0773..."
CLOUDFLARE_DATABASE_ID="01f30366-..."
CLOUDFLARE_D1_TOKEN="F8Cg..."

3. 設定 Prisma 配置檔案

確保您的專案有一個 prisma.config.ts 檔案。然後，設定 遷移驅動介面卡 以引用 D1。

prisma.config.ts

import path from 'node:path'
import type { PrismaConfig } from 'prisma'
import { PrismaD1HTTP } from '@prisma/adapter-d1'

// import your .env file
import 'dotenv/config'

type Env = {
  CLOUDFLARE_D1_TOKEN: string
  CLOUDFLARE_ACCOUNT_ID: string
  CLOUDFLARE_DATABASE_ID: string
}

export default {
  earlyAccess: true,
  schema: path.join('prisma', 'schema.prisma'),

  migrate: {
    async adapter(env) {
      return new PrismaD1HTTP({
        CLOUDFLARE_D1_TOKEN: env.CLOUDFLARE_D1_TOKEN,
        CLOUDFLARE_ACCOUNT_ID: env.CLOUDFLARE_ACCOUNT_ID,
        CLOUDFLARE_DATABASE_ID: env.CLOUDFLARE_DATABASE_ID,
      })
    },
  },
} satisfies PrismaConfig<Env>

4. 遷移您的資料庫

Prisma Migrate 現在將根據 prisma.config.ts 中提供的配置，對您的遠端 D1 資料庫執行遷移。

要使用此工作流更新遠端 schema，請執行以下命令：

npx prisma db push

注意

請注意，為了查詢資料庫，您仍然使用 @prisma/adapter-d1 包中的 PrismaD1 驅動介面卡。

import { PrismaD1HTTP } from '@prisma/adapter-d1'

使用 Wrangler CLI

Cloudflare D1 自帶其遷移系統。雖然我們建議您使用原生的 Prisma Migrate 工作流，但透過 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 命令，它會比較兩個 schemas（透過其 --to-X 和 --from-X 選項）並生成從一個 schema“演變”到另一個 schema 所需的步驟。這些 schemas 可以是 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-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-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

限制

不支援事務

Cloudflare D1 目前不支援事務（請參閱開放的功能請求）。因此，Prisma ORM 不支援 Cloudflare D1 的事務。當使用 Prisma 的 D1 介面卡時，隱式和顯式事務將被忽略並作為單獨的查詢執行，這破壞了事務 ACID 屬性的保證。

Prisma Migrate 僅支援遠端 D1 資料庫

Wrangler CLI 可以透過 --local 和 --remote 選項區分本地和遠端 D1（即 SQLite）資料庫例項。這種區別目前在原生的 Prisma Migrate 工作流中不可用。