Prisma Accelerate 常見問題疑難排解
在使用 Prisma Accelerate 時，您可能會在開發與營運過程中遇到特定錯誤代碼。瞭解這些錯誤的含義、發生原因以及解決方法，對於確保應用程式順利運作至關重要。本指南旨在協助您深入瞭解並逐步排除在使用 Prisma Accelerate 時遇到的特定錯誤代碼。
P6009 (ResponseSizeLimitExceeded)
當資料庫查詢的響應大小超過設定的查詢響應大小限制時，會觸發此錯誤。我們實施此限制是為了維護您的應用程式效能，因為在多個網路層之間傳輸超過 5MB 的資料會顯著拖慢應用程式速度。通常，在執行 ETL（擷取、轉換、載入）作業時，傳輸超過 5MB 的資料很常見。然而，對於其他場景（例如交易查詢、使用者介面即時資料獲取、大量資料更新，或在 ETL 之外的分析聚合大規模資料集），通常應儘量避免。這些使用案例雖然必要，但通常可以優化以符合設定的查詢響應大小限制，從而確保更流暢的效能與更好的使用者體驗。
P6009 的可能原因
響應中傳輸圖片/檔案
如果您獲取的資料表中包含圖片或檔案，可能會導致響應大小過大，進而引發此錯誤。通常不建議直接將資源儲存在資料庫中，因為這會嚴重影響資料庫的效能與擴展性。此外，這也會導致資料庫備份變慢，並大幅增加日常備份的儲存成本。
建議解決方案：將查詢響應大小限制設定得更大。如果仍然超出限制，請考慮將圖片或檔案儲存在 BLOB 儲存服務中，例如 Cloudflare R2、AWS S3 或 Cloudinary。這些服務允許您以最佳方式儲存資源並回傳存取連結（URL）。與其將資源直接儲存在資料庫中，不如只儲存 URL，這將大幅減少響應大小。
過度獲取資料 (Over-fetching)
在某些情況下，無意中獲取了大量記錄或欄位，導致超過了設定的查詢響應大小限制。這可能是由於查詢中的 where 子句不正確或完全缺失所致。
建議解決方案：將查詢響應大小限制設定得更大。如果仍然超出限制，請仔細檢查 where 子句是否如預期般過濾資料。為了防止獲取過多記錄，請考慮使用分頁 (pagination)。此外，請使用 select 子句僅返回必要的欄位，以縮減響應大小。
獲取海量資料
在許多資料處理工作流程中，特別是涉及 ETL（擷取-轉換-載入）流程或定期 CRON 工作時，需要從資料來源（如資料庫、API 或檔案系統）中擷取大量資料以進行分析、報告或進一步處理。如果您執行的 ETL/CRON 工作負載需要獲取大量資料進行分析處理，您可能會遇到此限制。
建議解決方案：將查詢響應大小限制設定得更大。如果仍然超出限制，請考慮將查詢拆分為批次處理。此方法可確保每個批次僅獲取一部分資料，從而避免單次作業超出大小限制。
P6004 (QueryTimeout)
當資料庫查詢未能在設定的查詢超時限制內返回響應時，會發生此錯誤。查詢超時限制包含等待連線池中連線的時間、網路傳輸至資料庫的延遲，以及查詢本身的執行時間。我們實施此限制是為了防止意外的長時間執行查詢，這可能會耗盡系統資源。
Accelerate 的跨區域網路傳輸時間不包含在設定的查詢超時限制內。
P6004 的可能原因
此錯誤可能由多種原因引起。其中一些突出的原因包括：
高流量與連線數不足
如果應用程式流量極高，且可用的資料庫連線數不足，查詢將需要等待連線變得可用。這種情況可能導致查詢等待連線的時間超過設定的查詢超時限制，若無法在期限內獲得處理，最終會觸發超時錯誤。
建議解決方案：在平台環境中設定 Accelerate 時，檢閱並考慮增加連線字串參數中指定的 connection_limit（參考文件）。此限制應與您的資料庫最大連線數保持一致。
預設情況下，連線限制為 10，除非您的資料庫連線字串中指定了不同的 connection_limit。
長時間執行的查詢
查詢回應可能變慢，即使有可用連線也會達到設定的查詢超時限制。這可能是因為單次查詢獲取了大量資料，或是資料表缺少適當的索引。
建議解決方案：將查詢超時限制設定得更大。如果超過限制，請識別執行緩慢的查詢並僅獲取必要的資料。使用 select 子句檢索特定欄位，避免獲取不必要的資料。此外，考慮加入適當的索引以提升查詢效率。您也可以將長時間執行的查詢隔離到獨立的環境中，以防止其影響交易查詢。
資料庫資源爭用
一個常見但棘手的問題是，當其他在同一個資料庫上執行的服務進行繁重的分析或資料處理任務時，會大量消耗資料庫資源。這些作業可能會佔用資料庫連線與處理能力，導致即使簡單的查詢也無法及時執行。這種「忙碌」或「干擾」的資料庫環境，會導致平時執行很快的查詢變得緩慢，甚至超時，尤其是在其他服務高活躍度期間。
使用者通常依賴 CPU 與記憶體使用率指標來評估資料庫負載，這可能會產生誤導。雖然這些是重要指標，但它們可能無法完全反映資料庫的運作狀態。讀取、寫入與等待時間等直接指標能更清楚地呈現資料庫效能，應密切監控。如果這些指標顯著惡化，特別是在查詢或資料模型沒有變化的情況下，這表明外部壓力正在影響資料庫效能。
建議解決方案：如果通常很快的查詢偶爾變慢或超時，且未對其進行任何修改，很可能是競爭查詢對同一個資料庫表格施加了壓力。為了進行診斷，請採取監控工具，或利用您資料庫的內建功能來觀察讀取、寫入與等待時間。這些監控將揭示與觀察到的效能下降相符的活動模式或峰值。
此外，定期檢查與優化關鍵查詢並確保資料表已正確建立索引至關重要。這種主動的方法可將這些查詢受競爭工作負載影響而變慢的可能性降至最低。
P6009 與 P6004 錯誤的考量
對於原生支援 Prisma ORM 的執行環境，您可以考慮建立兩個 PrismaClient 實例。一個使用 Accelerate 連線字串（以 prisma:// 為字首），另一個則使用直接的資料庫連線字串（以 postgres://、mysql:// 等為字首）。此方法的主要概念是針對特定查詢繞過 Accelerate。
然而，請注意，可用連線將會在您的兩個 PrismaClient 實例之間拆分。瞭解管理多個實例的含義至關重要，特別是在直接資料庫連線方面。使用帶有直接資料庫連線字串的 PrismaClient 實例意味著該連線將直接與您的資料庫進行互動。
這種方法需要謹慎考量，因為直接連線與由 Accelerate 管理的連線會共用底層相同的資料庫連線池。這可能會導致資源爭用，進而影響您資料庫服務的效能與可用性。
此外，直接連線可能會對您資料庫的效能與可用性產生重大影響。消耗大量資源的作業可能會對依賴同一個資料庫的其他使用者或處理程序造成服務降級。
如果您的應用程式執行環境原生支援 Prisma ORM，且您正在考慮採取此策略來繞過 P6009 和 P6004 錯誤，您可以建立兩個 PrismaClient 實例：
- 一個實例使用 Accelerate 連線字串（以
prisma://為字首）處理常規作業。 - 另一個實例使用直接資料庫連線字串（例如以
postgres://、mysql://等為字首）處理預期會超過設定的查詢超時限制，或是可能導致響應大小超過設定的查詢響應大小限制的特定作業。
export const prisma = new PrismaClient({
datasourceUrl: process.env.DIRECT_DB_CONNECTION,
})
export const prismaAccelerate = new PrismaClient({
datasourceUrl: process.env.ACCELERATE_CONNECTION,
}).$extends(withAccelerate())
這種設定允許您策略性地透過直接連線導向某些作業，從而降低遇到上述錯誤的風險。然而，在做出此決定時，應充分了解潛在後果，並評估您的資料庫基礎設施是否能在不損及整體效能與可用性的情況下支援額外的負載。
P6008 (ConnectionError|EngineStartError)
此錯誤表示 Prisma Accelerate 無法與您的資料庫建立連線，這可能有幾個原因。
P6008 的可能原因
資料庫無法公開存取
如果您的資料庫位於 VPC 內，或存取權限僅限於特定 IP 位址，而您未啟用 Accelerate 的靜態 IP，或是在資料庫防火牆中未允許這些靜態 IP，您可能會遇到此錯誤。
建議解決方案：為 Accelerate 啟用靜態 IP，並設定您的資料庫防火牆以允許來自這些靜態 IP 位址的連線。
無法存取的資料庫主機/埠
如果資料庫的伺服器位址（主機名稱）與埠號不正確或無法連線，您可能會遇到此錯誤。
建議解決方案：驗證建立 Prisma Accelerate 專案時提供的資料庫連線字串中的主機名稱與埠號。此外，嘗試使用資料庫 GUI 工具（例如 Prisma Studio、TablePlus 或 DataGrip）進行連線，以進行進一步調查。
錯誤的使用者名稱/密碼/資料庫名稱
當提供給 Prisma Accelerate 的憑證錯誤，導致其無法與您的資料庫建立連線時，可能會發生此錯誤。
建議解決方案：驗證提供給 Prisma Accelerate 的連線字串中的資料庫使用者名稱、密碼與名稱是否正確。確保這些憑證符合您資料庫的要求。使用直接資料庫 GUI 工具測試連線也有助於確認所提供的憑證是否正確。
資料庫回應時間過長
如果資料庫對連線請求的回應時間過長，Prisma Accelerate 可能會超時並拋出此錯誤。如果資料庫未處於啟動狀態或正在從睡眠模式中喚醒，可能會發生這種情況。
建議解決方案：確認資料庫已啟動且可存取。如果資料庫處於睡眠模式，請嘗試透過直接資料庫 GUI 工具發送請求，或使用資料庫的管理控制台將其喚醒。
P5011 (TooManyRequests)
當 Prisma Accelerate 偵測到請求量超過允許的閾值時，會發生此錯誤。這是一種保護措施，旨在保護 Prisma Accelerate 與您的底層資料庫免受過大負載的影響。
P5011 的可能原因
過於頻繁的重試迴圈
如果您的應用程式在收到特定錯誤後立即重試查詢，或僅以極短的延遲進行重試，快速累積的請求可能會超過閾值。
建議解決方案
- 實作指數退避 (exponential backoff) 策略。與其立即重試或採用固定延遲，不如在每次失敗嘗試後逐漸增加延遲時間。
- 這能讓系統有時間恢復，並減少壓垮 Prisma Accelerate 與您資料庫的可能性。
突發流量高峰
不可預測的流量激增（例如產品發布、限時搶購或病毒式傳播事件）可能導致達到閾值並產生 P5011 錯誤。
建議解決方案
- 請考慮針對 Prisma Accelerate 與您的資料庫採取主動擴展策略。
- 監控流量與資源使用率。如果您預期會有流量激增，請聯繫 支援團隊進行容量規劃與潛在的設定調整。
長時間或已排程的高負載工作
某些流程（如大量資料匯入、ETL 作業或長時間運行的 CRON 工作）可能會產生持續性的高查詢量。
建議解決方案
- 使用批次處理或區塊處理技術，將大型作業拆解為較小的部分。
- 建立限流或排程機制，以更均勻地分攤負載。
其他錯誤
MySQL (Aiven) 錯誤："We were unable to process your request. Please refresh and try again."
問題
當使用包含 ?ssl-mode=REQUIRED 參數的 Aiven MySQL 連線字串時，您可能會遇到以下錯誤：
We were unable to process your request. Please refresh and try again.
原因
ssl-mode=REQUIRED 參數與 Accelerate 不相容，這會導致連線問題。
建議解決方案
若要解決此錯誤，請從您的 MySQL 連線字串中移除 ?ssl-mode=REQUIRED 參數。
範例
- 原始連線字串：
mysql://username:password@host:port/database?ssl-mode=REQUIRED - 更新後的連線字串：
mysql://username:password@host:port/database