跳到主要內容

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 以增強安全性。在 平臺控制檯中瞭解如何為 Accelerate 啟用靜態 IP。

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

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

啟用後，系統會提示你生成一個 API 金鑰，你將在新的 Accelerate 連線字串中使用它來驗證請求。

用你新的 Accelerate 連線字串替換你的直接資料庫 URL。

.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 檔案中的 datasource url；

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

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

.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 或更高版本。

💡 Accelerate 擴充套件 @prisma/extension-accelerate 版本 2.0.0 及更高版本需要 Node.js 版本 18 或更高版本。

安裝最新版本的 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 Middleware，請確保它們在任何 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 秒的快取資料，然後在 Accelerate 在後臺獲取新資料時再提供 60 秒。

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

資訊

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

資訊

從 Prisma 版本 5.2.0 開始，你可以使用帶有 Accelerate 連線字串的 Prisma Studio。

使快取失效並保持快取的查詢結果最新​

如果你的應用程式需要即時或接近即時資料，快取失效可確保使用者看到最新資料，即使使用較大的 ttl（生存時間）或 swr（陳舊時重新驗證）快取策略。透過使快取失效，你可以繞過延長快取期，在需要時顯示即時資料。

例如，如果儀表板顯示客戶資訊，並且客戶的聯絡方式發生變化，快取失效允許你即時重新整理這些資料，確保支援人員始終看到最新資訊，而無需等待快取過期。

要使快取的查詢結果失效，你可以新增標籤，然後使用 $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;
}
© . This site is unofficial and not affiliated with Prisma Data, Inc.