Pulse: 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 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 after.

Example


const subscription = await prisma.user.subscribe({
  create: {},
})

Show event results

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: {},
})

Show event results

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 before. This represents the state of the record before the change event.

Example


const subscription = await prisma.user.subscribe({
  delete: {},
})

Show event results

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;

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 must wrap your filter criteria inside a before or after object depending on the type of event your subscription is listening for:

before: delete events
after: create and udpate events

This makes it explicit that the specified filter criteria apply to the before or 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 on the #pulse-feedback channel in our community Slack.

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 create events where the value of name is equal to 'Jim' after the event has occurred:


const subscription = await prisma.user.subscribe({
  create: {
    after: {
      name: 'Jim',
    },
  },
})

Show event results

Get update events where the value of name is equal to Jim after the event has occurred:


const subscription = await prisma.user.subscribe({
  create: {
    after: {
      name: 'Jim',
    },
  },
})

Show event results

Usage in the before state filter

Using a filter inside of before will return changed records that match your filter criteria as applied to the state of the record before the change event.

Example

Get delete events where the value of name was equal to Marc.


const subscription = await prisma.user.subscribe({
  delete: {
    before: {
      name: 'Jim',
    },
  },
})

Show event results

Specifying a filter condition for delete events only works if you’ve set the table’s REPLICA IDENTITY to FULL. See this section for more details.

Was this helpful?

Edit this page on GitHub

API Reference

Remarks

Database event filters

create

Example

update

Example

delete

Example

Filter conditions and operators

Usage in the after state filter

Examples

Usage in the before state filter

Example

Was this helpful?

Product

Developers

Use Cases

Company

Newsletter