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 },
  },
});

筛选更新后 `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`	一个对象，用于指定要接收的创建事件的过滤器。如果您将对象留空，使用 `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 },
  },
});

筛选更新后 `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>`

任何在数据库中发生的 create 事件都会返回类型为 PulseCreateEvent 的对象。

类型

PulseCreateEvent 具有以下字段

名称	类型	示例值	描述
`id`	`string`	`01HYBEER1JPSBVPG2NQADNQTA6`	遵循 ULID 规范的唯一标识符/幂等键。
`modelName`	`string`	`User`	受此事件影响的模型的名称。这是您 Prisma 架构中的模型名称。
`action`	`string`	`create`	在数据库中执行的写入操作类型：`create`
`created`	`User`	请参阅以下示例中的 `created`。	一个包含刚创建的记录的值的对象。

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

PulseCreateEvent<{

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

示例

以下是一个示例

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

`PulseUpdateEvent<User>`

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

类型

PulseUpdateEvent 具有以下字段

名称	类型	示例值	描述
`id`	`string`	`01HYBEER1JPSBVPG2NQADNQTA6`	遵循 ULID 规范的唯一标识符/幂等键。
`modelName`	`string`	`User`	受此事件影响的模型的名称。这是您 Prisma 架构中的模型名称。
`action`	`string`	`update`	在数据库中执行的写入操作类型：`update`
`before`	`User`	`null`	包含刚更新的记录的旧值的对象。这仅在数据库中的 `REPLICA IDENTITY` 设置为 `FULL` 时有效。否则，该值将始终为 `null`。
`after`	`User`	请参阅以下示例中的 `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',
  modelName: 'User'
}

已将 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',
  modelName: 'User'
}

`PulseDeleteEvent<User>`

タイプ

PulseDeleteEvent は、次のフィールドを持ちます。

名称	类型	示例值	描述
`id`	`string`	`01HYBEER1JPSBVPG2NQADNQTA6`	遵循 ULID 规范的唯一标识符/幂等键。
`modelName`	`string`	`User`	受此事件影响的模型的名称。这是您 Prisma 架构中的模型名称。
`action`	`string`	`delete`	データベースで実行された書き込み操作の種類: `create`、`update`、または `delete`。
`削除済み`	`User`	`{ 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',
  modelName: 'User'
}

已将 REPLICA IDENDITY 设置为 FULL

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

stream()​

说明​

选项​

返回类型​

示例​

使用 name 才能“恢复”流​

筛选 name 值不为空的新 User 记录​

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

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

subscribe()​

说明​

选项​

返回类型​

示例​

筛选 name 值不为空的新 User 记录​

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

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

stream() 与 subscribe() 的比较​

stop()​

对于 stream()​

对于 subscribe()​

PulseCreateEvent<User>​

类型​

示例​

PulseUpdateEvent<User>​

类型​

示例​

PulseDeleteEvent<User>​

タイプ​

例​

`stream()`

说明

选项

返回类型

示例

使用 `name` 才能“恢复”流

筛选 `name` 值不为空的新 `User` 记录

筛选更新后 `email` 以 `@prisma.io` 结尾的 `User` 记录

筛选 `email` 包含 `hello` 的已删除 `User` 记录

`subscribe()`

说明

选项

返回类型

示例

筛选 `name` 值不为空的新 `User` 记录

筛选更新后 `email` 以 `@prisma.io` 结尾的 `User` 记录

筛选 `email` 包含 `hello` 的已删除 `User` 记录

`stream()` 与 `subscribe()` 的比较

`stop()`

对于 `stream()`

对于 `subscribe()`

`PulseCreateEvent<User>`

类型

示例

`PulseUpdateEvent<User>`

类型

示例

`PulseDeleteEvent<User>`

タイプ

例