跳至主要内容

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，则在任何给定时间只能有一个客户端连接到具有该特定 name 的流。
create一个对象，用于指定要接收的创建事件的过滤器。如果您使用 create: {} 将对象留空，您将收到所有创建事件。您可以根据模型的任何标量字段进行过滤。
update一个包含 after 字段的对象，用于指定要接收的更新事件的过滤器。如果您使用 update: {} 将对象留空，您将收到所有更新事件。过滤器应用于执行更新后记录的值。您可以根据模型的任何标量字段进行过滤。
delete一个对象，用于指定要接收的删除事件的过滤器。您可以根据模型的任何标量字段进行过滤。

返回类型​

当不带任何过滤器参数调用时，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 值不为空的新 User 记录​

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

筛选更新后的 User 记录，其中更新后 email 以 @prisma.io 结尾​

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

筛选已删除的 User 记录，其中 email 包含 hello​

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一个对象，用于指定要接收的创建事件的过滤器。如果您使用 create: {} 将对象留空，您将收到所有创建事件。您可以根据模型的任何标量字段进行过滤。
update一个包含 after 字段的对象，用于指定要接收的更新事件的过滤器。如果您使用 update: {} 将对象留空，您将收到所有更新事件。过滤器应用于执行更新后记录的值。您可以根据模型的任何标量字段进行过滤。
delete一个对象，用于指定要接收的删除事件的过滤器。您可以根据模型的任何标量字段进行过滤。

返回类型​

当不带任何过滤器参数调用时，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 值不为空的新 User 记录​

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

筛选更新后的 User 记录，其中更新后 email 以 @prisma.io 结尾​

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

筛选已删除的 User 记录，其中 email 包含 hello​

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 类型的对象由数据库中发生的任何 create 事件返回。

类型​

PulseCreateEvent 具有以下字段

名称类型示例值描述
id字符串01HYBEER1JPSBVPG2NQADNQTA6一个唯一的标识符/幂等键，遵循 ULID 规范。
action字符串create在数据库中执行的写入操作的类型：create
createdUser请参见下面的示例中的 created。一个包含刚刚创建的记录值的对象。

事件的类型是您模型字段的泛型。在本例中，对于上面的 User 模型，它如下所示

PulseCreateEvent<{

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

示例​

这是一个示例

{
  action: 'create',
  created: { id: 3, email: '[email protected]', name: 'Jane Doe' },
  id: '0/2A5A590'
}

PulseUpdateEvent<User>​

数据库中发生的任何 delete 事件都会返回一个 PulseUpdateEvent 类型的对象。

类型​

一个 PulseUpdateEvent 具有以下字段

名称类型示例值描述
id字符串01HYBEER1JPSBVPG2NQADNQTA6一个唯一的标识符/幂等键，遵循 ULID 规范。
action字符串update在数据库中执行的写入操作类型：update
beforeUsernull包含刚刚更新的记录的旧值的的对象。这仅在数据库中的 REPLICA IDENTITY 设置为 FULL 时有效。否则，该值将始终为 null。
afterUser请参阅下面示例中的 after。包含刚刚更新的记录的新值的的对象。

事件的类型是您模型字段的泛型。在本例中，对于上面的 User 模型，它如下所示

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

示例​

未将 REPLICA IDENDITY 设置为 FULL

{
  action: 'update',
  after: { id: 2, email: '[email protected]', name: 'Jane Doe' },
  before: null,
  id: '0/2A5A248'
}

已将 REPLICA IDENDITY 设置为 FULL

{
  action: 'update',
  after: { id: 2, email: '[email protected]', name: 'Jane Doe' },
  before: { id: 2, email: '[email protected]', name: null },
  id: '0/2A5A248'
}

PulseDeleteEvent<User>​

类型​

一个 PulseDeleteEvent 具有以下字段

名称类型示例值描述
id字符串01HYBEER1JPSBVPG2NQADNQTA6一个唯一的标识符/幂等键，遵循 ULID 规范。
action字符串delete在数据库中执行的写入操作类型：create、update 或 delete。
deletedUser{ id: 3 }包含刚刚删除的记录的值的对象。这仅在数据库中的 REPLICA IDENTITY 设置为 FULL 时有效。否则，该对象将仅包含一个 id 字段。

事件的类型是您模型字段的泛型。在本例中，对于上面的 User 模型，它如下所示

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

示例​

未将 REPLICA IDENDITY 设置为 FULL

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

已将 REPLICA IDENDITY 设置为 FULL

 {
  action: 'delete',
  deleted: { id: 42, email: '[email protected]', name: 'Jane Doe' },
  id: '0/2A5A398'
}