API 參考

Accelerate API 參考文件基於以下 Schema

model User {
  id    Int     @id @default(autoincrement())
  name  String?
  email String  @unique
}

所有示例均基於 User 模型。

cacheStrategy

藉助 Prisma Client 的 Accelerate 擴充套件，你可以使用 cacheStrategy 引數進行模型查詢，並使用 ttl 和 swr 引數來定義 Accelerate 的快取策略。Accelerate 擴充套件要求你安裝 Prisma Client 版本 4.10.0。

選項

cacheStrategy 引數接受一個帶有以下鍵的選項

選項	示例	型別	必需	描述
swr	60	整數	否	過期後重新驗證時間（秒）。
ttl	60	整數	否	存活時間（秒）。
標籤	["user"]	字串陣列	否	tag 用作控制應用程式中特定查詢失效的變數。它是一個可選的字串陣列，用於使快取失效，每個標籤只能包含字母數字字元和下劃線，最大長度為 64 個字元。

示例

為查詢新增快取策略，定義 60 秒的過期後重新驗證 (SWR) 值、60 秒的存活 (TTL) 值以及快取標籤 "emails_with_alice"

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

支援的 Prisma Client 操作

以下是支援 cacheStrategy 的所有讀取查詢操作列表

• findUnique()
• findUniqueOrThrow()
• findFirst()
• findFirstOrThrow()
• findMany()
• count()
• aggregate()
• groupBy()

資訊

cacheStrategy 引數不支援任何寫入操作，例如 create()。

withAccelerateInfo

任何支援 cacheStrategy 的查詢都可以附加 withAccelerateInfo() 來封裝響應資料幷包含有關 Accelerate 響應的額外資訊。

要檢索響應狀態，請使用

const { data, info } = await prisma.user
  .count({
    cacheStrategy: { ttl: 60, swr: 600 },
    where: { myField: 'value' },
  })
  .withAccelerateInfo()

console.dir(info)

資訊

請注意響應物件的 info 屬性。請求資訊儲存在此處。

返回型別

info 物件型別為 AccelerateInfo，並遵循以下介面

interface AccelerateInfo {
  cacheStatus: 'ttl' | 'swr' | 'miss' | 'none'
  lastModified: Date
  region: string
  requestId: string
  signature: string
}

屬性	型別	描述
快取狀態	"ttl" | "swr" | "miss" | "none"	響應的快取狀態。 ttl 表示在 ttl 持續時間內發生快取命中，且未執行資料庫查詢 swr 表示在 swr 持續時間內發生快取命中，且資料正在由 Accelerate 在後臺重新整理 miss 表示 ttl 和 swr 都已過期，並且請求執行了資料庫查詢 none 表示未指定快取策略，並且請求執行了資料庫查詢
上次修改	日期	響應上次重新整理的日期。
區域	字串	接收請求的資料中心區域。
請求 ID	字串	請求的唯一識別符號。有助於故障排除。
簽名	字串	Prisma 操作的唯一簽名。

$accelerate.invalidate

你可以使用 $accelerate.invalidate API 使快取失效。

注意

要按需使快取查詢結果失效，需要付費計劃。每個計劃每天允許的基於快取標籤的失效次數有具體限制，但呼叫 $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;
}

注意

每次呼叫最多可以使 5 個標籤失效。

$accelerate.invalidateAll

你可以使用 $accelerate.invalidateAll API 使整個快取失效。

示例

要使以下查詢失效

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

只需呼叫 $accelerate.invalidateAll API

try {
  await prisma.$accelerate.invalidateAll();
} catch (e) {
  if (e instanceof Prisma.PrismaClientKnownRequestError) {
    if (e.code === "P6003") {
      console.log(
        "The cache invalidation rate limit has been reached. Please try again later."
      );
    }
  }
  throw e;
}

為什麼要使用 $accelerate.invalidateAll?

此方法比 invalidate("all") 等替代方案提供更好的編輯器支援（例如 IntelliSense）。

警告

這將清除整個環境的快取——請謹慎使用。

提供自定義 Fetch 實現

從 Accelerate 2.0.0 版開始，在透過 Accelerate 擴充套件 Prisma Client 時，你可以提供 fetch 函式的自定義實現。這使你能夠更靈活地控制應用程式中 HTTP 請求的處理方式。

要傳遞自定義 fetch 實現，可以使用以下模式

const myFetch = (input: URL, init?: RequestInit): Promise<Response> => {
  // Your custom fetch logic here
  return fetch(input, init);
};

const prisma = new PrismaClient().$extends(withAccelerate({ fetch: myFetch }));

錯誤

與 Prisma Accelerate 相關的錯誤以 P6xxx 開頭。

你可以在此處找到 Prisma Accelerate 的完整錯誤程式碼參考。