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

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

邊緣函式，例如 Cloudflare Workers，是一種輕量級的無伺服器計算形式，分佈在全球各地。它們允許您將應用程式部署和執行到儘可能靠近終端使用者的位置。

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

遵循 Cloudflare 的地理分散式原則，並將計算和資料更接近應用程式使用者，D1 支援自動讀複製：它根據資料庫接收到的查詢數量和來源，動態管理資料庫例項和只讀副本的位置。

這意味著讀查詢將針對離查詢發起位置最近的 D1 例項執行。

雖然您也可以與其他資料庫提供商使用 Prisma ORM 的讀副本，但這通常需要您使用 讀副本客戶端擴充套件。使用 D1 時，無需專用客戶端擴充套件即可開箱即用地支援讀副本。

另一方面，對於寫操作，查詢仍會傳輸到單個主例項，以便將更改傳播到所有讀副本並確保資料一致性。

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

在 Prisma，我們相信 Cloudflare 正在引領未來應用程式的構建和部署方式。

您可以透過這篇部落格文章瞭解我們如何將 Cloudflare 視為改善 Data DX 的合作伙伴：重塑開發者體驗：Prisma & Cloudflare 引領 Data DX 之路

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

作為 Cloudflare 技術的堅定支持者，我們很高興地宣佈，您現在可以在 Cloudflare Workers（和 Pages）中使用 Prisma ORM 來訪問 D1 資料庫。

請注意，此功能基於目前處於預覽階段的驅動介面卡，因此我們也認為 D1 支援處於預覽階段。

Prisma ORM 和 D1 入門

接下來，您將找到從頭開始設定和部署一個透過 Prisma ORM 訪問 D1 資料庫的 Cloudflare Worker 的分步說明。

截至此版本，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 schema 檔案。
• 它建立了一個 .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 控制檯 中找到它，或者在終端中執行 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 模型

現在，在您的終端中執行以下命令，生成建立與上述 User 模型等效的 User 表的 SQL 語句

這將在您之前的遷移檔案 migrations/0001_ceate_user_table.sql 中儲存一個建立新 User 表的 SQL 語句，它看起來像這樣

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

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

在本教程中，您將兩者都做：在本地測試 Worker，然後再部署它。因此，您需要執行這兩個命令。開啟您的終端並貼上以下命令。

首先，針對您的本地資料庫執行模式更改

接下來，針對遠端資料庫

兩次都被提示確認是否應用遷移時，請點選 Return 鍵。

您的本地和遠端 D1 例項現在都包含 User 表。

我們再建立一些可以在 Worker 執行後查詢的虛擬資料。這次，您將執行 SQL 語句，而不將其儲存在檔案中。

再次，首先針對您的本地資料庫執行該命令

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

您現在在本地和遠端資料庫例項中都有一個虛擬記錄。您可以在 .wrangler/state 中找到本地 SQLite 檔案，而遠端檔案可以在 Cloudflare 控制檯中檢視。

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://:8787 檢視資料庫查詢結果

7. 部署 Worker

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

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

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

立即試用

我們很想聽聽您對 Prisma ORM 中新 D1 支援的看法！請試用並向我們反饋您的意見，您可以在 GitHub 或 Discord 上分享。編碼愉快 ✌️