Getting started with Prisma Pulse
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
- The connection string of a Pulse-ready database (if you don't have one yet, you can configure your existing database 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 , 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
- Enable Static IP if your database is using IP allowlisting. Learn more about enabling static IP for Pulse here.
- decide whether you want to use the Automatic setup for Database replication (only available on paid plans)
- make sure Event persistence is enabled to use delivery guarantees with
.stream()
(or disable it if you want to use.subscribe()
for fully ephemeral events without delivery guarantees)
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.1.0
or higher.
Install the Pulse 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 })
)
Runtime-specific imports
If you're using "moduleResolution":"bundler"
in your tsconfig.json
file and your Pulse extension version is 1.2.0
or greater, import the Pulse extension based on your runtime:
- Node.js
- Cloudflare Workers
import { withPulse } from '@prisma/extension-pulse/node';
import { withPulse } from '@prisma/extension-pulse/workerd';
Using the correct runtime-specific import prevents the following error:
Cannot find module '@prisma/extension-pulse' or its corresponding type declarations.
2.3. Create your first Pulse stream
With the Pulse extension applied, you can use Pulse's .stream()
method on any model defined in your Prisma Schema to stream data change events.
In the below example, it is assumed that your Prisma schema has a User
model. A stream is created for the User
model that listens for any change event on that table:
- Stream
- 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 stream = await prisma.user.stream()
for await (const event of stream) {
console.log('just received an event:', event)
}
}
main()
model User {
id Int @id @default(autoincrement())
email String @unique
name String?
}
3. Test your stream
After running the code snippet above, you can test the stream 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 stream, for example:
Stream only create
events:
const stream = await prisma.user.stream({
create: { },
})
Stream only update
events:
const stream = await prisma.user.stream({
update: { },
})
Stream only delete
events:
const stream = await prisma.user.stream({
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.