Getting started
Prerequisites
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:
- A Prisma Data Platform account
- The connection string of a Pulse-ready database (if you don't have one yet, you can configure your database the instructions here or use a Railway template)
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
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:
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
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:
- Subscription
- Prisma schema
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()
model User {
id Int @id @default(autoincrement())
email String @unique
name String?
}
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.