跳到主要內容

API 參考文檔

本頁面上的 Pulse API 參考文檔基於以下結構描述

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

stream()​

stream() 返回一個 異步可迭代物件，它接收與您調用此方法的表相關的所有資料庫變更事件。

const stream = await prisma.user.stream();

由於返回的是異步可迭代物件，您可以使用 for await...of 迴圈來等待和接收事件

for await (let event of subscription) {
  console.log(event);
}

注意​

  • 使用 stream() 需要在您的 Pulse 專案中啟用 事件持久性。
  • stream() 保證所有事件至少會被傳遞一次，且順序正確。

選項​

您可以將帶有配置選項的物件傳遞給 stream()。該物件具有以下欄位

名稱描述
名稱串流的名稱。提供此選項可啟用「可恢復性」，並確保即使您的串流在事件實際發生時未處於活動狀態（例如，因為您的伺服器已關閉），您稍後仍會收到事件。請注意，如果提供了 name，則在任何給定時間，只有一個客戶端可以連接到具有該特定 name 的串流。
建立一個物件，用於指定要接收的建立事件的篩選器。如果您將物件留空，例如 create: {}，您將接收所有建立事件。您可以根據模型的任何純量欄位進行篩選。
更新一個帶有 after 欄位的物件，用於指定要接收的更新事件的篩選器。如果您將物件留空，例如 update: {}，您將接收所有更新事件。篩選器應用於執行更新後記錄的值。您可以根據模型的任何純量欄位進行篩選。
刪除一個物件，用於指定要接收的刪除事件的篩選器。您可以根據模型的任何純量欄位進行篩選。

返回類型​

當在沒有篩選器參數的情況下調用時，stream() 方法會返回以下類型

const stream: PulseSubscription<
  | PulseCreateEvent<{
      id: number;
      name: string | null;
      email: string;
    }>
  | PulseUpdateEvent<{
      id: number;
      name: string | null;
      email: string;
    }>
  | PulseDeleteEvent<{
      id: number;
      name: string | null;
      email: string;
    }>
> = await prisma.user.stream();

根據您提供的參數，返回類型可能會更改。例如，如果您僅篩選 create 事件，類型將會調整

const stream: PulseSubscription<
  PulseCreateEvent<{
    id: number;
    email: string;
    name: string | null;
  }>
> = await prisma.user.stream({
  create: {},
});

範例​

使用 name 以便能夠「恢復」串流​

const stream = await prisma.user.stream({
  name: "all-user-events",
});

在此處了解更多關於恢復串流的資訊。

篩選 name 值不為 null 的新 User 記錄​

const stream = await prisma.user.stream({
  create: {
    name: { not: null },
  },
});

篩選更新後 email 以 @prisma.io 結尾的已更新 User 記錄​

const stream = await prisma.user.stream({
  update: {
    after: {
      email: { endsWith: "@prisma.io" },
    },
  },
});

篩選 email 包含 hello 的已刪除 User 記錄​

const stream = await prisma.user.stream({
  delete: {
    email: { contains: "hello" },
  },
});

subscribe()​

subscribe() 返回一個 異步可迭代物件，它接收與您調用此方法的表相關的所有資料庫變更事件。

const subscription = await prisma.user.subscribe();

由於返回的是異步可迭代物件，您可以使用 for await...of 迴圈來等待和接收事件

for await (let event of subscription) {
  console.log(event);
}

注意​

  • subscribe() 保證所有事件最多只會被傳遞一次。不保證事件到達的順序。
  • 使用 subscribe() 傳遞的事件是暫時性的，這表示如果您的訂閱在資料庫中發生事件時未處於活動狀態（例如，因為您的伺服器已關閉），則不會傳遞這些事件。

選項​

您可以將帶有配置選項的物件傳遞給 subscribe()。該物件具有以下欄位

名稱描述
建立一個物件，用於指定要接收的建立事件的篩選器。如果您將物件留空，例如 create: {}，您將接收所有建立事件。您可以根據模型的任何純量欄位進行篩選。
更新一個帶有 after 欄位的物件，用於指定要接收的更新事件的篩選器。如果您將物件留空，例如 update: {}，您將接收所有更新事件。篩選器應用於執行更新後記錄的值。您可以根據模型的任何純量欄位進行篩選。
刪除一個物件，用於指定要接收的刪除事件的篩選器。您可以根據模型的任何純量欄位進行篩選。

返回類型​

當在沒有篩選器參數的情況下調用時，subscribe() 方法會返回以下類型

const subscription: PulseSubscription<
  | PulseCreateEvent<{
      id: number;
      name: string | null;
      email: string;
    }>
  | PulseUpdateEvent<{
      id: number;
      name: string | null;
      email: string;
    }>
  | PulseDeleteEvent<{
      id: number;
      name: string | null;
      email: string;
    }>
> = await prisma.user.subscribe();

根據您提供的參數，返回類型可能會更改。例如，如果您僅篩選 create 事件，類型將會調整

const subscription: PulseSubscription<
  PulseCreateEvent<{
    id: number;
    email: string;
    name: string | null;
  }>
> = await prisma.user.subscribe({
  create: {},
});

範例​

篩選 name 值不為 null 的新 User 記錄​

const subscription = await prisma.user.subscribe({
  create: {
    name: { not: null },
  },
});

篩選更新後 email 以 @prisma.io 結尾的已更新 User 記錄​

const subscription = await prisma.user.subscribe({
  update: {
    after: {
      email: { endsWith: "@prisma.io" },
    },
  },
});

篩選 email 包含 hello 的已刪除 User 記錄​

const subscription = await prisma.user.subscribe({
  delete: {
    email: { contains: "hello" },
  },
});

stream() 與 subscribe() 的比較​

對於大多數用例，建議使用 stream() 選項，因為它可以保證事件到達消費者端。但請注意，由於 stream() 需要啟用事件持久性，因此這會對 事件儲存和成本 產生影響。

請參閱更詳細的比較。

stop()​

允許您顯式停止串流和訂閱並關閉連線。這是為了確保每個表允許的訂閱數量不會耗盡。

對於 stream()​

// Create the stream
const stream = await prisma.user.stream();

// ... Use the stream

// Stop the stream
stream.stop();

對於 subscribe()​

// Create the subscription
const subscription = await prisma.user.subscribe();

// ... Use the subscription

// Stop the subscription
subscription.stop();

PulseCreateEvent<User>​

PulseCreateEvent 類型的物件由資料庫中發生的任何建立事件返回。

類型​

PulseCreateEvent 具有以下欄位

名稱類型範例值描述
id字串01HYBEER1JPSBVPG2NQADNQTA6遵循 ULID 規範的唯一識別符 / 冪等鍵。
動作字串建立在資料庫中執行的寫入操作類型：create
已建立User請參閱以下範例中的 created。一個包含剛建立的記錄值的物件。

事件的類型是通用於模型欄位的。在上述 User 模型的情況下，它看起來如下所示

PulseCreateEvent<{

  email: string;
  name: string | null;
}>;

範例​

這是一個範例

{
  action: 'create',
  created: { id: 3, email: 'jane@prisma.io', name: 'Jane Doe' },
  id: '0/2A5A590'
}

PulseUpdateEvent<User>​

PulseUpdateEvent 類型的物件由資料庫中發生的任何更新事件返回。

類型​

PulseUpdateEvent 具有以下欄位

名稱類型範例值描述
id字串01HYBEER1JPSBVPG2NQADNQTA6遵循 ULID 規範的唯一識別符 / 冪等鍵。
動作字串更新在資料庫中執行的寫入操作類型：update
之前Usernull一個包含剛更新的記錄舊值的物件。這僅在資料庫中的 REPLICA IDENTITY 設定為 FULL 時才有效。否則，該值將始終為 null。
之後User請參閱以下範例中的 after。一個包含剛更新的記錄新值的物件。

事件的類型是通用於模型欄位的。在上述 User 模型的情況下，它看起來如下所示

PulseUpdateEvent<{
  id: number;
  email: string;
  name: string | null;
}>;

範例​

未將 REPLICA IDENTITY 設定為 FULL 的情況

{
  action: 'update',
  after: { id: 2, email: 'doe@prisma.io', name: 'Jane Doe' },
  before: null,
  id: '0/2A5A248'
}

已將 REPLICA IDENTITY 設定為 FULL 的情況

{
  action: 'update',
  after: { id: 2, email: 'support@prisma.io', name: 'Jane Doe' },
  before: { id: 2, email: 'support@prisma.io', name: null },
  id: '0/2A5A248'
}
注意

要使用 FULL 設定啟用 REPLICA IDENTITY，您必須在每個表的基礎上配置它，因為預設情況下未啟用它。這需要對您的資料庫執行 SQL 查詢。在此處了解更多資訊。

PulseDeleteEvent<User>​

類型​

PulseDeleteEvent 具有以下欄位

名稱類型範例值描述
id字串01HYBEER1JPSBVPG2NQADNQTA6遵循 ULID 規範的唯一識別符 / 冪等鍵。
動作字串刪除在資料庫中執行的寫入操作類型：create、update 或 delete。
已刪除User{ id: 3 }一個包含剛刪除的記錄值的物件。這僅在資料庫中的 REPLICA IDENTITY 設定為 FULL 時才有效。否則，該物件將僅包含 id 欄位。

事件的類型是通用於模型欄位的。在上述 User 模型的情況下，它看起來如下所示

PulseDeleteEvent<{
  id: number;
  email: string;
  name: string | null;
}>;

範例​

未將 REPLICA IDENTITY 設定為 FULL 的情況

 {
  action: 'delete',
  deleted: { id: 1 },
  id: '0/2A5A398'
}

已將 REPLICA IDENTITY 設定為 FULL 的情況

 {
  action: 'delete',
  deleted: { id: 42, email: 'doe@prisma.io', name: 'Jane Doe' },
  id: '0/2A5A398'
}
注意

要使用 FULL 設定啟用 REPLICA IDENTITY，您必須在每個表的基礎上配置它，因為預設情況下未啟用它。這需要對您的資料庫執行 SQL 查詢。在此處了解更多資訊。