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() vs 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 | string | 01HYBEER1JPSBVPG2NQADNQTA6 | 遵循 ULID 规范的唯一标识符/幂等键。 |
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'
}
PulseUpdateEvent<User>
PulseUpdateEvent 类型的对象由数据库中发生的任何 delete 事件返回。
类型
PulseUpdateEvent 具有以下字段
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
id | string | 01HYBEER1JPSBVPG2NQADNQTA6 | 遵循 ULID 规范的唯一标识符/幂等键。 |
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'
}
已将 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'
}
要使用 FULL 设置启用 REPLICA IDENTITY，您必须在每个表的基础上进行配置，因为它默认情况下未启用。这需要针对您的数据库执行 SQL 查询。在此处了解更多信息。
PulseDeleteEvent<User>
类型
PulseDeleteEvent 具有以下字段
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
id | string | 01HYBEER1JPSBVPG2NQADNQTA6 | 遵循 ULID 规范的唯一标识符/幂等键。 |
action | string | delete | 在数据库中执行的写入操作类型：create、update 或 delete。 |
deleted | 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'
}
已将 REPLICA IDENDITY 设置为 FULL 的情况
{
action: 'delete',
deleted: { id: 42, email: '[email protected]', name: 'Jane Doe' },
id: '0/2A5A398'
}
要使用 FULL 设置启用 REPLICA IDENTITY，您必须在每个表的基础上进行配置，因为它默认情况下未启用。这需要针对您的数据库执行 SQL 查询。在此处了解更多信息。