Prisma Accelerate 入門指南

先決條件

開始使用 Accelerate，您需要以下條件

• A
• 一個使用 Prisma Client 4.16.1 或更高版本的專案。如果您的專案使用互動式交易，則需要使用 5.1.1 或更高版本。（我們始終建議使用最新版本的 Prisma。）
• 託管的 PostgreSQL、MySQL/MariaDB、PlanetScale、CockroachDB 或 MongoDB 資料庫

1. 啟用 Accelerate

導航到您的 Prisma Data Platform 專案，選擇一個環境，並透過提供您的資料庫連線字串並選擇離您的資料庫最近的區域來啟用 Accelerate。

注意

如果您需要 IP 白名單或具有受信任 IP 位址的防火牆設定，請啟用靜態 IP 以增強安全性。請參閱 如何在 Platform Console 中為 Accelerate 啟用靜態 IP 以了解更多資訊。

2. 將 Accelerate 新增到您的應用程式

2.1. 更新您的資料庫連線字串

啟用後，系統會提示您產生 API 金鑰，您將在新 Accelerate 連線字串中使用該金鑰來驗證請求。

將您的直接資料庫 URL 替換為新的 Accelerate 連線字串。

.env

# New Accelerate connection string with generated API_KEY
DATABASE_URL="prisma://accelerate.prisma-data.net/?api_key=__API_KEY__"

# Previous (direct) database connection string
# DATABASE_URL="postgresql://user:password@host:port/db_name?schema=public"

您更新後的連線字串將在您的 Prisma schema 檔案中用作資料來源 url；

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

Prisma Migrate 和 Introspection 無法與 prisma:// 連線字串一起使用。為了繼續使用這些功能，請在名為 DIRECT_DATABASE_URL 的 .env 檔案中新增一個變數，其值為直接資料庫連線字串

.env

DATABASE_URL="prisma://accelerate.prisma-data.net/?api_key=__API_KEY__"
DIRECT_DATABASE_URL="postgresql://user:password@host:port/db_name?schema=public"

然後在您的 Prisma schema 的 datasource 區塊中新增一個名為 directUrl 的欄位，並包含以下內容

datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")
  directUrl = env("DIRECT_DATABASE_URL")
}

當提供此設定時，遷移和內省將使用 directUrl 連線字串，而不是在 url 中定義的字串。

directUrl 對於您執行遷移和內省很有用。但是，您不需要 directUrl 即可在您的應用程式中使用 Accelerate。

注意

如果您將 Prisma 與 PostgreSQL 搭配使用，則不需要 directUrl，因為 Prisma Migrate 和 Introspection 可以與 prisma+postgres:// 連線字串一起使用。

2.2. 安裝 Accelerate Prisma Client 擴充功能

資訊

💡 Accelerate 需要 Prisma Client 版本 4.16.1 或更高版本，以及 @prisma/extension-accelerate 版本 1.0.0 或更高版本

安裝最新版本的 Prisma Client 和 Accelerate Prisma Client 擴充功能

npm install @prisma/client@latest @prisma/extension-accelerate

2.3. 為 Accelerate 產生 Prisma Client

如果您使用 Prisma 版本 5.2.0 或更高版本，Prisma Client 將根據資料庫連線字串中的協定自動判斷應如何連線到資料庫。如果 DATABASE_URL 中的連線字串以 prisma:// 開頭，Prisma Client 將嘗試使用 Prisma Accelerate 連線到您的資料庫。

在長時間運行的應用程式伺服器（例如部署在 AWS EC2 上的伺服器）中使用 Prisma Accelerate 時，您可以執行以下命令來產生 Prisma Client

npx prisma generate

在無伺服器或邊緣應用程式中使用 Prisma Accelerate 時，我們建議您執行以下命令來產生 Prisma Client

npx prisma generate --no-engine

--no-engine 標誌可防止 Query Engine 檔案包含在產生的 Prisma Client 中，這可確保應用程式的捆綁包大小保持較小。

警告

如果您的 Prisma 版本低於 5.2.0，請使用 --accelerate 選項產生 Prisma Client

npx prisma generate --accelerate

如果您的 Prisma 版本低於 5.0.0，請使用 --data-proxy 選項產生 Prisma Client

npx prisma generate --data-proxy

2.4. 使用 Accelerate 擴充功能擴充您的 Prisma Client 實例

新增以下內容以使用 Accelerate 擴充功能擴充您現有的 Prisma Client 實例

import { PrismaClient } from '@prisma/client'
import { withAccelerate } from '@prisma/extension-accelerate'

const prisma = new PrismaClient().$extends(withAccelerate())

如果您要部署到邊緣執行時環境（例如 Cloudflare Workers、Vercel Edge Functions、Deno Deploy 或 Supabase Edge Functions），請改用我們的邊緣用戶端

import { PrismaClient } from '@prisma/client/edge'
import { withAccelerate } from '@prisma/extension-accelerate'

const prisma = new PrismaClient().$extends(withAccelerate())

如果 VS Code 無法識別 $extends 方法，請參閱 本節，了解如何解決此問題。

將 Accelerate 擴充功能與其他擴充功能或中介軟體搭配使用

由於 擴充功能是依序套用的，請確保您以正確的順序套用它們。擴充功能無法共享行為，並且最後套用的擴充功能優先。

如果您在應用程式中使用 Prisma Optimize，請確保在 Accelerate 擴充功能之前套用它。例如

const prisma = new PrismaClient().$extends(withOptimize()).$extends(withAccelerate())

如果您在應用程式中使用 Prisma 中介軟體，請確保它們在任何 Prisma Client 擴充功能（如 Accelerate）之前新增。例如

const prisma = new PrismaClient().$use(middleware).$extends(withAccelerate())

2.5. 在您的資料庫查詢中使用 Accelerate

withAccelerate 擴充功能主要執行兩件事

• 讓您可以存取每個適用模型方法中的 cacheStrategy 欄位，讓您可以為每個查詢定義快取策略。
• 透過連線池化器路由您的所有查詢。

沒有快取策略僅使用連線池

如果您只想利用 Accelerate 的連線池化功能，而不套用快取策略，您可以像沒有 Accelerate 一樣執行查詢。

透過啟用 Accelerate 並提供 Accelerate 連線字串，您的查詢現在預設使用連線池化器。

定義快取策略

使用新的 cacheStrategy 屬性更新查詢，讓您可以為該特定查詢定義快取策略

const user = await prisma.user.findMany({
  where: {
    email: {
      contains: 'alice@prisma.io',
    },
  },
  cacheStrategy: { swr: 60, ttl: 60 },
})

在上面的範例中，swr: 60 和 ttl: 60 表示 Accelerate 將為快取資料提供 60 秒的服務，然後再提供 60 秒的服務，同時 Accelerate 在背景中提取最新資料。

您現在應該會看到快取查詢的效能有所提升。

資訊

有關哪種策略最適合您的應用程式的資訊，請參閱 選擇快取策略。

資訊

從 Prisma 版本 5.2.0 開始，您可以將 Prisma Studio 與 Accelerate 連線字串搭配使用。

使快取失效並保持快取查詢結果為最新狀態

如果您的應用程式需要即時或近乎即時的資料，快取失效可確保使用者看到最新的資料，即使在使用大型 ttl (Time-To-Live) 或 swr (Stale-While-Revalidate) 快取策略 時也是如此。透過使快取失效，您可以繞過延長的快取期間，以便在需要時顯示即時資料。

例如，如果儀表板顯示客戶資訊，並且客戶的聯絡方式詳細資訊發生變更，快取失效可讓您立即刷新該資料，確保支援人員始終看到最新的資訊，而無需等待快取過期。

若要使快取查詢結果失效，您可以新增標籤，然後使用 $accelerate.invalidate API。

注意

隨需快取失效適用於我們的付費方案。如需更多詳細資訊，請參閱我們的定價。

若要使以下查詢失效

await prisma.user.findMany({
  where: {
    email: {
      contains: "alice@prisma.io",
    },
  },
  cacheStrategy: {
    swr: 60,
    ttl: 60,
    tags: ["emails_with_alice"],
  },
});

您需要在 $accelerate.invalidate API 中提供快取標籤

try {
  await prisma.$accelerate.invalidate({
    tags: ["emails_with_alice"],
  });
} catch (e) {
  if (e instanceof Prisma.PrismaClientKnownRequestError) {
    // The .code property can be accessed in a type-safe manner
    if (e.code === "P6003") {
      console.log(
        "You've reached the cache invalidation rate limit. Please try again shortly."
      );
    }
  }
  throw e;
}