跳到主要內容

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 存取。
  • 進行 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 命令使用此遷移系統，以在您的檔案系統上建立和管理遷移檔案。

此命令無法協助您找出 SQL 陳述式，以建立需要放入這些遷移檔案內部的資料庫 schema。如果您想使用 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 或 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