Skip to main content

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: {},
})
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 deleted. This represents the state of the record before the change event.

Example​
const subscription = await prisma.user.subscribe({
  delete: {},
})
Show event results
warning

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.

info

All create event results implicitly represent the after state of the change event. And all delete event results implicitly represent the before state of the change event.

info

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',
    },
  },
})
Show event results