Skip to main content

Getting started

Prerequisites​

info

Prisma Pulse currently supports PostgreSQL. We'd love to hear which databases you would like to see supported next.

To get started with Pulse, you will need the following:

1. Enable Pulse in the Platform Console​

1.1. Choose the environment you want to enable Pulse for​

Open the Platform Console, navigate to your workspace of choice, then select the project and choose the environment in which you want to enable Pulse.

If you don't have a project yet in your workspace, you can create a new one.

1.2. Enable Pulse​

In the project environment of your choice, click the Enable Pulse button.

1.3. Configure Pulse​

The Pulse Setup screen requires you to:

  • provide your Database connection string
  • select a Region where Pulse should be hosted
  • decide whether you want to use the Automatic setup for Database replication (only available on paid plans)

When you're done with that, click the Enable Pulse button at the bottom of the screen. This will test the connectivity to your database.

1.4. Generate an API key​

info

If you already have an API key for your current environment, you can skip this step und use the existing API key for using Prisma Pulse.

You can generate an API key by clicking the Generate API key button. Store the API key in a secure location or add it to the .env file of your project:

.env
PULSE_API_KEY="your_secure_pulse_api_key"

You won't be able to access the same API key again afterwards.

2. Add Pulse to your application​

With Pulse enabled, proceed with these steps to integrate Pulse into your application. You can also utilize our example repository on GitHub as a reference guide.

2.1. Install the Pulse Client extension​

info

Pulse requires Prisma Client version 4.16.1 or higher and @prisma/extension-pulse version 1.0.1 or higher

Install the Pulse Client extension:

npm install @prisma/extension-pulse@latest

2.2. Extend your Prisma Client instance with the Pulse extension​

Add the following to extend your existing Prisma Client instance with the Prisma Pulse extension:

import { PrismaClient } from '@prisma/client'
import { withPulse } from '@prisma/extension-pulse'

const prisma = new PrismaClient().$extends(
  withPulse({ apiKey: process.env.PULSE_API_KEY })
)

2.3. Create your first Pulse subscription​

With the Pulse extension applied, you can use Pulse's subscribe() method on any model defined in your Prisma Schema to subscribe to data change events.

In the below example, it is assumed that your Prisma schema has a User model. A subscription is made to that User model that listens for any change event on that table:

import { PrismaClient } from '@prisma/client'
import { withPulse } from '@prisma/extension-pulse'

const prisma = new PrismaClient().$extends(
  withPulse({ apiKey: process.env.PULSE_API_KEY })
)

async function main() {
  const subscription = await prisma.user.subscribe()

  for await (const event of subscription) {
    console.log('just received an event:', event)
  }
}

main()

3. Test your subscription​

After running the code snippet above, you can test the subscription by creating, updating or deleting a User record in your database.

You can do that using Prisma Studio (by running npx prisma studio) or by using any other database client of your choice (like Postico or psql).

If everything worked, you should see the event being logged to the terminal where you can the code snippet from above. 🎉

Next steps​

You can try out more filters on your Pulse subscription, for example:

Subscribe only to create events:

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

Subscribe only to update events:

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

Subscribe only to delete events:

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

Pulse offers even more fine-grained filters than these. You can explore these in the API reference.

Need help?​

Reach out to us in the #help-and-questions channel on our Discord, or connect with our community to see how others are using Pulse.