使用 Prisma ORM 和 Cloudflare D1 (預覽版) 在邊緣建構應用程式

使用 D1 將您的資料庫帶到邊緣

邊緣函數，例如 Cloudflare Workers，是一種輕量級無伺服器運算形式，分佈在全球各地。它們讓您可以盡可能靠近終端使用者部署和執行您的應用程式。

D1 是 Cloudflare 針對邊緣環境的原生無伺服器資料庫。它基於 SQLite，可用於部署使用 Cloudflare 的應用程式。D1 最初於 2022 年推出。

遵循 Cloudflare 的地理分佈原則以及將運算和資料更靠近應用程式使用者，D1 支援自動讀取複寫：它會根據資料庫收到的查詢數量以及查詢來源動態管理資料庫實例的數量和唯讀複本的位置。

這表示讀取查詢會針對最靠近發出查詢位置的 D1 實例執行。

雖然您也可以將讀取複本與 Prisma ORM 和其他資料庫供應商一起使用，但這通常需要您使用 Read Replica Client 擴充功能。當使用 D1 時，開箱即支援讀取複本，而無需專用的 Client 擴充功能。

另一方面，對於寫入操作，查詢仍然會傳輸到單一主要實例，以便將變更傳播到所有讀取複本並確保資料一致性。

Prisma ORM 現在支援 D1 🚀 (預覽版)

在 Prisma，我們相信 Cloudflare 處於建構應用程式未來建構和部署方式的最前沿。

您可以透過這篇部落格文章深入了解我們如何將 Cloudflare 視為改善 Data DX 的合作夥伴：重新定義開發人員體驗：Prisma 和 Cloudflare 引領 Data DX 之路

支援 D1 一直是 GitHub 上 Prisma ORM 最受歡迎的功能請求之一。

作為 Cloudflare 技術供應商的堅定信徒，我們很高興分享您現在可以在 Cloudflare Workers (和 Pages) 內使用 Prisma ORM 來存取 D1 資料庫。

請注意，此功能基於目前處於預覽版的 驅動程式配接器，因此我們也認為 D1 支援也處於預覽版。

Prisma ORM 和 D1 入門

在下文中，您將找到從頭開始設定和部署 Cloudflare Worker 以及透過 Prisma ORM 存取 D1 資料庫的逐步說明。

截至本次發布，Prisma Migrate 尚未完全與 D1 相容。在本教學課程中，您將結合使用 D1 的遷移系統和 prisma migrate diff 命令來產生和執行遷移。

先決條件

• 您的機器上已安裝 Node.js 和 npm
• Cloudflare 帳戶

1. 建立 Cloudflare Worker

第一步，繼續使用 npm create 來引導 Cloudflare Worker 的純文字版本 (使用 Cloudflare 的 hello-world 範本)。在您的終端機中執行以下命令

這將彈出 CLI 精靈。每次出現問題時，按 Return 鍵以選取所有預設選項。

在精靈結束時，您應該在網域 https://prisma-d1-example.USERNAME.workers.dev 上部署 Cloudflare Worker，該網域只會在瀏覽器中呈現 "Hello World"

2. 初始化 Prisma ORM

Worker 就緒後，讓我們繼續設定 Prisma ORM。

首先，導覽至專案目錄並安裝 Prisma CLI

接下來，安裝 Prisma Client 套件以及 D1 的驅動程式配接器

最後，使用以下命令引導 Prisma ORM 所需的檔案

此命令執行了兩項操作

• 它建立了一個名為 prisma 的新目錄，其中包含您的 Prisma 結構描述檔案。
• 它建立了一個 .env 檔案，該檔案通常用於設定將由 Prisma CLI 讀取的環境變數。

在本教學課程中，您不需要 .env 檔案，因為 Prisma ORM 和 D1 之間的連線將透過繫結進行。您將在下一步中找到設定此繫結的說明。

由於您將使用目前處於預覽版的驅動程式配接器功能，因此您需要透過 generator 區塊上的 previewFeatures 欄位明確啟用它。

開啟您的 schema.prisma 檔案並調整 generator 區塊，使其如下所示

3. 建立 D1 資料庫

在此步驟中，您將設定您的 D1 資料庫。一般來說，有兩種方法可以做到這一點。可以使用 Cloudflare Dashboard UI 或透過 wrangler CLI。在本教學課程中，您將使用 CLI。

開啟您的終端機並執行以下命令

如果一切順利，您應該會看到類似於此的輸出

您現在在您的 Cloudflare 帳戶中擁有一個 D1 資料庫，並繫結到您的 Cloudflare Worker。

複製命令輸出的最後一部分並將其貼到您的 wrangler.toml 檔案中。它應該看起來類似於這樣

請注意，上面程式碼片段中的 __YOUR_D1_DATABASE_ID__ 是一個預留位置，應替換為您自己的 D1 實例的資料庫 ID。如果您無法從終端機輸出中取得此 ID，您也可以在 Cloudflare Dashboard 中找到它，或在您的終端機中執行 npx wrangler d1 info prisma-demo-db。

接下來，您將在資料庫中建立資料庫表，以便能夠使用 Prisma ORM 將一些查詢傳送到 D1。

4. 在資料庫中建立表

D1 隨附其自己的透過 wrangler d1 migrate 命令的 遷移系統。此遷移系統與 Prisma CLI 配合良好，Prisma CLI 提供工具，讓您可以產生結構描述變更的 SQL 陳述式。所以您可以

• 使用 D1 的原生遷移系統來建立遷移檔案並將其套用至您的 D1 實例
• 使用 Prisma CLI 來產生任何結構描述變更的 SQL 陳述式

在下文中，您將同時使用 D1 的遷移系統和 Prisma CLI 來建立遷移並針對您的資料庫執行遷移。

首先，使用 wrangler CLI 建立新的遷移

當系統提示命令是否可以建立名為 migrations 的新資料夾時，按 Return 鍵以確認。

該命令現在已建立一個名為 migrations 的新目錄，以及一個名為 0001_create_user_table.sql 的空檔案。

接下來，您需要將建立 User 表的 SQL 陳述式新增到該檔案。開啟 schema.prisma 檔案並將以下 User 模型新增至其中

現在，在您的終端機中執行以下命令，以產生 SQL 陳述式，該陳述式會建立與上述 User 模型等效的 User 表

這會將 SQL 陳述式儲存到您的遷移檔案 migrations/0001_ceate_user_table.sql 中，以建立新的 User 表，以下是其外觀

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

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

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

首先，針對您的 local 資料庫執行結構描述變更

接下來，針對 remote 資料庫

當系統提示您確認是否應套用遷移時，兩次都按 Return 鍵。

您的本機和 remote D1 實例現在都包含 User 表。

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

同樣，先針對您的 local 資料庫執行命令

最後，針對您的 remote 資料庫執行它

您現在在本機和 remote 資料庫實例中都有一個虛擬記錄。您可以在 .wrangler/state 中找到本機 SQLite 檔案，而可以在 Cloudflare Dashboard 中檢查 remote 檔案。

5. 從 Worker 查詢您的資料庫

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

1. 將 DB 新增至 Env 介面。
2. 使用 PrismaD1 驅動程式配接器來實例化 PrismaClient。
3. 使用 Prisma Client 傳送查詢並傳回結果。

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

在執行 Worker 之前，您需要使用以下命令產生 Prisma Client

6. 在本機執行 Worker

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

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

7. 部署 Worker

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

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

恭喜，您剛剛部署了 Cloudflare Worker，使用 D1 作為資料庫並透過 Prisma ORM 查詢它 🎉

立即試用

我們很想知道您對 Prisma ORM 中新的 D1 支援有何看法！請試用並在 GitHub 或 Discord 上與我們分享您的意見反應。祝您編碼愉快 ✌️