API reference
The Pulse API reference documentation is based on the following schema:
model User {
id Int @id @default(autoincrement())
name String?
email String @unique
}
All example are based on the User
model.
subscribe
subscribe
returns all data change events related to the table you call this method on:
const subscription = await prisma.user.subscribe()
Remarks
Passing an empty object to the subscribe
function will also behaves the same as passing no argument to the function:
const subscription = await prisma.user.subscribe({})
Database event filters
Inside of the subscribe()
method you can use filters to get specific events and data. The three filter options currently supported are described below:
create
You can use the create
filter to retrieve all create events on a table. A create event is triggered when a new record is created in a table.
Pulse returns the values of the new record as an object named created
. This represents the state of the record after the create event.
Example
const subscription = await prisma.user.subscribe({
create: {},
})
update
You can use the update
filter to retrieve all update events on a table. An update event is triggered when a value in a database record has changed.
Pulse returns the values of the changed record as an object named after
. This represents the state of the record after the change event.
Example
const subscription = await prisma.user.subscribe({
update: {},
})
delete
You can use the delete
filter to retrieve all delete events on a table. A delete event is triggered when a record has been removed from the database.
Pulse returns the values of the changed record as an object named deleted
. This represents the state of the record before the change event.
Example
const subscription = await prisma.user.subscribe({
delete: {},
})
By default, the response for delete
events will only return the primary key of the record. To get the before values of all fields in the record, you must set REPLICA IDENTITY
to FULL
on the table(s) you want to get field values for. If this is not configured, defining a filter for deletes will only be possible on the primary key.
For example, running the following SQL command will set the REPLICA IDENTITY
to FULL
on a table named User
:
ALTER TABLE public."User" REPLICA IDENTITY FULL;
stop
Allows you to explicitly stop subscriptions and close the connection. This is needed to ensure that the limited number of subscriptions allowed per table is not exhausted.
async function main() {
// Subscribe to new events on the `user` table
const subscription = await prisma.user.subscribe({})
// Set a timeout to the subscription after 60 seconds.
// Explicitly stopping the subscriptions and closing the connection is needed
// to not exhaust the limited number of subscriptions allowed per table.
setTimeout(() => {
console.log('Stopping the subscription.')
subscription.stop()
}, 60000)
// Waiting loop that prints new events when something changes in the database
for await (const event of subscription) {
console.log('new event:', event) // 'create', 'update', 'delete'
}
}
main()
Filter conditions and operators
Pulse allows you to subscribe to change events based on filter conditions and operators. Pulse supports all of Prisma Client’s supported filter conditions and operators except for search
and mode
. You also won't be able to define filters that reference other models via relations.
You may have to wrap your filter criteria inside a after
object depending on the type of event your subscription is listening for:
after
:update
events
This makes it explicit that the specified filter criteria apply to the after
state of the change event.
In the future, Pulse may support the ability to return both the before
and after
state of update
change events and filter on either state. If these are features you’re interested in, please let us know by sharing your thoughts on our Discord.
Usage in the after state filter
Using a filter inside of after
will return changed records that match your filter criteria as applied to the state of the record after the change event.
Examples
Get update
events where the value of name is equal to Jim
after the event has occurred:
const subscription = await prisma.user.subscribe({
update: {
after: {
name: 'Jim',
},
},
})