在 Prisma Postgres 中進行查詢快取
Prisma Postgres 支援內建查詢快取，以減輕資料庫負載並提升查詢效能。您可以使用所有讀取查詢中提供的 cacheStrategy 選項來設定快取行為。
此功能由透過 Prisma Accelerate 啟用的內部快取層提供支援，但除非您使用自己的資料庫，否則無需直接與 Accelerate 互動。
在 Prisma Postgres 中設定快取
若要在您的 Prisma Postgres 專案中啟用查詢快取，您需要設定 Accelerate 快取並安裝用戶端擴充功能。請依照下列步驟操作：
1. 在平台控制台（Platform Console）中啟用快取
- 前往並導覽至您的專案儀表板
- 在「連線至您的資料庫」（Connect to your database）區段中，點擊連線（Connect）
- 切換啟用 Accelerate 快取（Enable Accelerate caching）以啟動快取層
- 複製產生的連線字串
您的連線字串看起來會像這樣
DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=ey...."
將 .env 檔案中的連線字串替換為這個新的已啟用 Accelerate 的 URL。
2. 安裝 Accelerate 擴充功能
在您的專案中安裝所需的用戶端擴充功能
npm install @prisma/extension-accelerate
3. 設定帶有快取的 Prisma Client
更新您的 Prisma Client 設定以使用 Accelerate 擴充功能
- 標準執行時期 (Standard runtime)
- Edge 執行時期 (Edge runtime)
import { PrismaClient } from '../generated/prisma/client'
import { withAccelerate } from '@prisma/extension-accelerate'
const prisma = new PrismaClient({
accelerateUrl: process.env.DATABASE_URL,
}).$extends(withAccelerate())
import { PrismaClient } from '@prisma/client/edge'
import { withAccelerate } from '@prisma/extension-accelerate'
const prisma = new PrismaClient({
accelerateUrl: process.env.DATABASE_URL,
}).$extends(withAccelerate())
4. 開始快取您的查詢
設定完成後，您可以使用 cacheStrategy 選項將快取新增至任何讀取查詢中
await prisma.user.findMany({
cacheStrategy: {
ttl: 60, // Cache for 60 seconds
},
})
您的快取設定現已完成！繼續閱讀以了解不同的快取策略以及如何針對您的使用案例進行最佳化。
快取策略
對於 Prisma Client 中的所有讀取查詢，您可以定義設定快取行為的 cacheStrategy 參數。快取策略允許您定義快取的兩個主要特性：
- 存活時間 (TTL)：快取回應被視為新鮮 (fresh) 的持續時間（以秒為單位）。
- 過期後再驗證 (SWR)：當快取在背景中重新整理時，過期的快取回應仍被視為可接受的持續時間（以秒為單位）。
存活時間 (TTL)
存活時間 (TTL) 決定了快取資料被視為新鮮的時間。透過以秒為單位指定 ttl，您可以控制資料在快取中保持有效的持續時間。當執行讀取查詢時，如果快取的回應在 ttl 限制內，Prisma Client 會從快取中擷取資料，而無需查詢資料庫。如果快取資料不可用或已過期，Prisma Client 會查詢資料庫並將結果儲存在快取中，以供後續請求使用。
在 cacheStrategy 中使用 ttl 並以秒為單位指定查詢的 TTL
await prisma.user.findMany({
cacheStrategy: {
ttl: 60,
},
});
設定 60 秒的 TTL 後，大多數請求在 TTL 持續時間內都會產生快取命中
TTL 對於減少不需要頻繁更新的資料的資料庫負載和延遲非常有用。
使 TTL 失效並保持您的快取查詢結果為最新
如果您的應用程式需要即時或近乎即時的資料，快取失效（Cache Invalidation）可確保使用者即使在使用較長的 ttl (存活時間) 時，也能看到最新的資料。透過使快取失效，您可以繞過較長的快取週期，在需要時隨時顯示即時資料。
例如，如果儀表板顯示客戶資訊，而客戶的聯絡詳細資訊發生了變更，TTL (存活時間) 設定可確保快取在設定的持續時間後自動過期。這允許系統在下次存取時僅重新整理更新後的資料，確保支援人員無需手動重新整理快取即可始終看到最新資訊。
然而，在需要於 TTL 過期前進行立即更新的情況下，快取失效允許系統主動從快取中清除特定資料。這會強制立即重新整理更新後的資訊，因此支援人員無需等待 TTL 觸發即可始終擁有最新的詳細資訊。
若要使快取查詢結果失效，您可以新增標籤，然後使用 $accelerate.invalidate API。
按需快取失效功能適用於我們的付費方案。如需詳細資訊，請參閱我們的定價頁面。
若要使下方的查詢失效，您需要在 $accelerate.invalidate API 中提供快取標籤
await prisma.user.findMany({
cacheStrategy: {
ttl: 60,
tags: ["findMany_users"],
},
});
// This is how you would invalidate the cached query above.
await prisma.$accelerate.invalidate({
tags: ["findMany_users"],
});
過期後再驗證 (SWR)
過期後再驗證 (SWR) 允許您控制 Prisma Postgres 在背景擷取新鮮資料的同時，提供過期快取資料的時長。當執行讀取查詢時，Prisma Postgres 會根據 swr 持續時間檢查快取回應的存活時間。如果快取資料在 swr 限制內，Prisma Postgres 會提供過期資料，同時透過從資料庫擷取最新資料來同步重新整理快取。
在 cacheStrategy 中使用 swr 並以秒為單位指定查詢的 SWR
await prisma.user.findMany({
cacheStrategy: {
swr: 60,
},
});
當指定 60 秒的 SWR 時，快取會提供過期資料，直到快取在每次請求後於背景中自行重新整理
使 SWR 失效並保持您的快取查詢結果為最新
如果您的應用程式需要即時或近乎即時的資料，快取失效可確保使用者即使在使用較長的 swr (過期後再驗證) 時，也能看到最新的資料。透過使快取失效，您可以繞過較長的快取週期，在需要時隨時顯示即時資料。
例如，考慮一個顯示倉庫產品庫存水位的儀表板。透過 SWR (過期後再驗證) 設定，即使資料稍微過時，儀表板也可以立即顯示最後已知的庫存資料，同時在背景中擷取新資料。這確保了員工無需等待即可繼續使用最近的資訊，庫存水位會在重新驗證完成後立即更新。
然而，在需要立即更新庫存資料的情況下（例如產品庫存不足且計數需要即時準確性時），快取失效允許系統主動從快取中清除特定資料。這會強制立即重新整理最新的庫存資料，因此員工無需等待 SWR 完成重新驗證即可始終獲得最新的詳細資訊。
若要使快取查詢結果失效，您可以新增標籤，然後使用 $accelerate.invalidate API。
按需快取失效功能適用於我們的付費方案。如需詳細資訊，請參閱我們的定價頁面。
若要使下方的查詢失效，您需要在 $accelerate.invalidate API 中提供快取標籤
await prisma.user.findMany({
cacheStrategy: {
swr: 60,
tags: ["findMany_users"],
},
});
// This is how you would invalidate the cached query above.
await prisma.$accelerate.invalidate({
tags: ["findMany_users"],
});
選擇快取策略
快取有助於改善查詢回應時間並減輕資料庫負載。然而，這也意味著您可能會向用戶端提供過期的資料。是否可以接受提供過期資料以及達到何種程度，取決於您的使用案例。ttl 和 swr 是您可以用來調整快取行為的參數。
使用 TTL 的快取策略
當可以接受過期的快取資料時，請使用 TTL 來減少資料庫負載。
使用案例：電子商務應用程式中的產品目錄
考慮一個不常變更產品目錄的電子商務應用程式。透過設定 1 小時的 ttl，Prisma Client 可以在該小時內為後續的使用者請求提供快取的產品資料，而無需存取資料庫。這顯著減少了資料庫負載並改善了產品列表頁面的回應時間。
何時失效：如果有對目錄的重大更新（例如價格大幅變動或產品庫存調整），則應立即使快取失效，以防止客戶看到過時的資訊。
使用 SWR 的快取策略
使用 SWR 可以快速回應請求，並將過期資料的影響降至最低。雖然它不會減少資料庫負載，但它可以顯著改善回應時間。
使用案例：社交媒體平台上的使用者個人資料
想像一個經常存取使用者個人資料的社交媒體平台。透過利用 5 分鐘的 swr，Prisma Postgres 可以快速提供快取的使用者個人資料資訊，從而減少個人資料頁面的延遲。同時，它會在每次請求後在背景重新整理快取，確保對個人資料所做的任何更新最終都會反映在後續的請求中。
何時失效：如果使用者對其個人資料進行了重大更新（例如變更個人資料圖片或簡介），應立即使快取失效，以確保追蹤者無需等待 SWR 重新整理即可看到最新的更新。
使用 TTL + SWR 的快取策略
若要獲得非常快速的回應時間並減少資料庫負載，請同時使用 TTL 和 SWR。您可以使用此策略來微調應用程式對過期資料的容忍度。
在 cacheStrategy 中使用 ttl 和 swr，並以秒為單位指定查詢的 TTL 和 SWR
await prisma.user.findMany({
cacheStrategy: {
ttl: 30,
swr: 60,
},
});
當指定 30 秒的 TTL 和 60 秒的 SWR 時，快取會在最初的 30 秒內提供新鮮資料。隨後，它會提供過期資料，直到快取在每次請求後於背景中自行重新整理
使用案例：新聞文章
考慮一個新聞應用程式，文章經常被存取但不需要即時更新。透過設定 2 小時的 ttl 和 5 分鐘的 swr，Prisma Client 可以快速提供快取的文章，從而減少讀者的延遲。只要文章在 ttl 限制內，使用者就能獲得快速回應。在 ttl 過期後，Prisma Client 會繼續提供過期的文章長達額外的 5 分鐘，並在回應新查詢時透過資料庫中的最新新聞重新驗證快取。這有助於在效能和新鮮度之間保持平衡。
何時失效：如果發布了關鍵更新或突發新聞文章，應立即使快取失效，以確保讀者能及時看到最新資訊。此方法對於某些新聞項目可能需要繞過正常快取週期以保持時效性的應用程式特別有用。
按需快取失效
如果您的應用程式需要即時或近乎即時的資料，快取失效可確保使用者即使在使用較長的 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(
"The cache invalidation rate limit has been reached. Please try again later."
);
}
}
throw e;
}
探索演示應用程式，以透過清晰的時間軸查看 Prisma Postgres 中的快取查詢結果如何按需失效。
預設快取策略
Prisma Postgres 預設為不快取 (no cache)，以避免意外問題。雖然快取可以提升效能，但使用不當可能會導致錯誤。
例如，如果在未指定快取策略的情況下在關鍵路徑上執行查詢，結果可能會不正確，且沒有明確的解釋。此問題通常發生在無意中啟用了隱式快取時。
為了避免此類問題，您必須明確選擇加入（opt-in）快取。這確保您知道預設並未啟用快取，從而防止潛在錯誤。
當未指定快取策略或發生快取未命中 (cache miss) 時，快取層會透過靠近資料庫區域的連線池執行個體將所有查詢路由至資料庫。