跳至主要內容

如何使用 Prisma ORM 搭配 Cloudflare D1

簡介​

本指南將說明如何使用 Prisma ORM 搭配 Cloudflare D1，這是一個在 Cloudflare 的邊緣網路執行的無伺服器 SQL 資料庫。您將學習如何設定 Prisma ORM 與 D1、處理遷移，以及將您的應用程式部署到 Cloudflare Workers。您可以在 GitHub 上找到已準備好部署的範例。

先決條件​

在開始本指南之前，請確保您已具備

  • 一個 Cloudflare 帳戶
  • 已安裝 Node.js (16 或更高版本)
  • 已安裝 Wrangler CLI (3.39.0 或更高版本)
  • 對 Cloudflare Workers 和 D1 的基本熟悉

1. 設定 Prisma 結構描述​

在您的 Prisma 結構描述中，將 driverAdapters 預覽功能新增至 generator 區塊，並將 datasource 的 provider 設定為 sqlite。如果您只是使用 prisma init 啟動 Prisma 結構描述，也請務必將下列 User 模型新增至其中

schema.prisma
generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
}

2. 安裝相依性​

接下來，安裝所需的套件

npm install @prisma/adapter-d1

此外，請務必使用高於 wrangler@^3.39.0 的 Wrangler CLI 版本，否則在接下來的章節中使用的 --remote 標記將無法使用。

3. 設定 D1 資料庫連線​

若要將您的 Workers 連線至 D1 執行個體，請將下列繫結新增至您的 wrangler.toml

wrangler.toml
name = "prisma-cloudflare-worker-example"
main = "src/index.ts"
compatibility_date = "2024-03-20"
compatibility_flags = ["nodejs_compat"]

[[d1_databases]]
binding = "DB" # i.e. available in your Worker on env.DB
database_name = "__YOUR_D1_DATABASE_NAME__" # to be replaced
database_id = "__YOUR_D1_DATABASE_ID__"     # to be replaced

請注意，上述程式碼片段中的 __YOUR_D1_DATABASE_NAME__ 和 __YOUR_D1_DATABASE_ID__ 是應取代為您自己的 D1 執行個體的資料庫名稱和 ID 的預留位置。

如果您無法從終端機輸出取得此 ID，您也可以在 Cloudflare 儀表板中找到它，或在您的終端機中執行 npx wrangler d1 list 和 npx wrangler d1 info __YOUR_D1_DATABASE_NAME__ 來找到。

4. 設定資料庫遷移​

使用 D1 的遷移系統建立並套用遷移

# Create migration directory and file
npx wrangler d1 migrations create __YOUR_D1_DATABASE_NAME__ create_user_table

再次將 __YOUR_D1_DATABASE_NAME__ 取代為您的資料庫名稱，並在出現提示時，確認您想要建立 migrations 目錄。執行此命令後，應該會有一個名為 migrations 的新資料夾，其中包含一個名為 0001_create_user_table.sql 的檔案。

您現在可以產生建立 User 資料表所需的 SQL 陳述式，該資料表可以對應至 Prisma 結構描述中的 User 模型，如下所示

# Generate SQL using Prisma Migrate
npx prisma migrate diff --from-empty --to-schema-datamodel ./prisma/schema.prisma --script --output migrations/0001_create_user_table.sql

請注意，產生的 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");

您現在需要使用 wrangler d1 migrations apply 命令，將此 SQL 陳述式傳送至 D1。請注意，此命令接受兩個選項

  • --local：針對 D1 的本機版本執行陳述式。此 D1 的本機版本將是一個 SQLite 資料庫檔案，位於您的專案中。當您想要在本機電腦上開發和測試您的 Worker 時，此方法很有用。請參閱Cloudflare 文件，以了解更多資訊。
  • --remote：針對您 D1 的遠端版本執行陳述式。此版本由您已部署的 Cloudflare Workers 使用。請參閱Cloudflare 文件，以了解更多資訊。

在本教學課程中，您將同時執行這兩個步驟：在本機測試 Worker 並 在之後部署它。因此，您需要執行這兩個命令。開啟您的終端機並貼上以下命令

# For the local database
npx wrangler d1 migrations apply __YOUR_D1_DATABASE_NAME__ --local

# For the remote database
npx wrangler d1 migrations apply __YOUR_D1_DATABASE_NAME__ --remote

和之前一樣，您需要將 __YOUR_D1_DATABASE_NAME__ 取代為您 D1 資料庫的名稱。

讓我們也建立一些虛擬資料，以便在 Worker 執行後進行查詢。這次，您將執行 SQL 陳述式，而不會將其儲存在檔案中

# For the local database
npx wrangler d1 execute __YOUR_D1_DATABASE_NAME__ --command "INSERT INTO  \"User\" (\"email\", \"name\") VALUES
('jane@prisma.io', 'Jane Doe (Local)');" --local

# For the remote database
npx wrangler d1 execute __YOUR_D1_DATABASE_NAME__ --command "INSERT INTO  \"User\" (\"email\", \"name\") VALUES
('jane@prisma.io', 'Jane Doe (Remote)');" --remote

5. 實作 Worker​

在將 Prisma Client 查詢新增至您的 Worker 之前，您需要使用以下命令產生 Prisma Client

npx prisma generate

若要使用 Prisma ORM 從 Worker 查詢您的資料庫，您需要

  1. 將 DB 繫結新增至 Env 介面。(或者，您可以執行 npx wrangler types，從一個名為 worker-configuration.d.ts 的個別檔案中的繫結產生 Env 類型。)
  2. 使用 PrismaD1 驅動程式轉接器，具現化 PrismaClient。
  3. 使用 Prisma Client 傳送查詢並傳回結果。

開啟 src/index.ts 並將整個內容取代為以下內容

src/index.ts
import { PrismaClient } from '@prisma/client'
import { PrismaD1 } from '@prisma/adapter-d1'

export interface Env {
  DB: D1Database
}

export default {
  async fetch(
    request: Request,
    env: Env,
    ctx: ExecutionContext
  ): Promise<Response> {
    const adapter = new PrismaD1(env.DB)
    const prisma = new PrismaClient({ adapter })

    const users = await prisma.user.findMany()
    const result = JSON.stringify(users)
    return new Response(result)
  },
}

6. 在本機執行 Worker​

在資料庫查詢就緒且已產生 Prisma Client 的情況下，您可以繼續在本機執行 Worker

npm run dev

現在您可以開啟瀏覽器，前往 https://127.0.0.1:8787，以查看資料庫查詢的結果

;[{ id: 1, email: 'jane@prisma.io', name: 'Jane Doe (Local)' }]

7. 設定 DATABASE_URL 環境變數並部署 Worker​

若要部署 Worker，請執行以下命令

npm run deploy

您的已部署 Worker 可透過 https://prisma-d1-example.USERNAME.workers.dev 存取。如果您在瀏覽器中導覽至該 URL，您應該會看到從遠端 D1 資料庫查詢的以下資料

;[{ id: 1, email: 'jane@prisma.io', name: 'Jane Doe (Remote)' }]

後續步驟​

現在您已設定 Prisma ORM 與 Cloudflare D1，您可以

  • 使用 Prisma 強大的查詢 API 新增更複雜的查詢
  • 設定 Prisma Studio 進行資料庫管理
  • 實作資料庫監控
  • 新增自動化測試

如需更多資訊和更新