API 參考

Prisma Postgres API 參考文件基於以下 Schema

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

所有示例均基於 User 模型。

cacheStrategy

藉助適用於 Prisma Postgres 的 Prisma 客戶端擴充套件，你可以將 cacheStrategy 引數用於模型查詢，並使用 ttl 和 swr 引數為你的 Prisma Postgres 查詢定義快取策略。此客戶端擴充套件要求你安裝 Prisma Client 4.10.0 版本。

選項

cacheStrategy 引數接受一個包含以下鍵的選項

選項	示例	型別	必需	描述
swr	60	Int	否	過時資料重新驗證（stale-while-revalidate）時間，單位為秒。
ttl	60	Int	否	存活時間（time-to-live），單位為秒。
tags	["user"]	String[]	否	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()，以包裝響應資料幷包含有關快取響應的額外資訊。

要檢索響應狀態，請使用

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
}

屬性	型別	描述
cacheStatus	"ttl" | "swr" | "miss" | "none"	響應的快取狀態。 ttl 表示在 ttl 持續時間內命中快取，且未執行資料庫查詢 swr 表示在 swr 持續時間內命中快取，Prisma Postgres 正在後臺重新整理資料 miss 表示 ttl 和 swr 都已過期，並且請求執行了資料庫查詢 none 表示未指定快取策略，並且請求執行了資料庫查詢
lastModified	日期	響應上次重新整理的日期。
region	String	接收請求的資料中心區域。
requestId	String	請求的唯一識別符號。有助於故障排除。
signature	String	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）。

警告

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

錯誤

Prisma Postgres 相關錯誤以 P6xxx 開頭。

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