Getting started
Prerequisites
To participate in Pulse's Early Access program, you need to meet the following prerequisites:
- A GitHub account.
- A project that uses Prisma Client
4.16.1
or higher. - A publicly accessible PostgreSQL database.
- Ability to use the superuser account of the database instance. In the future, we will support the ability to connect to your database from Pulse with a limited access, non-superuser account.
- An invitation to Pulse's Early Access program.
You will also need a database with the following configurations:
- PostgreSQL version 12+.
- Ensure your database is publicly accessible.
- Set the
wal_level
setting in PostgreSQL tological
. - A database superuser that can be used for connections inside Pulse.
1. Database setup
General database configuration
Required settings
wal_level
Some providers may not allow direct access to this setting. If you are unable to change this setting, please refer to the provider-specific guides for further assistance.
ALTER SYSTEM SET wal_level = logical;
You will need to restart the database after changing this setting.
Optional settings
The following increases the memory usage of the write-ahead log on your PostgreSQL database. We suggest setting these values initially and adjusting them if necessary.
max_replication_slots
ALTER SYSTEM SET max_replication_slots = 20;
wal_keep_size
ALTER SYSTEM SET wal_keep_size = 2048;
Provider specific configuration
Railway
Railway.app offers an excellent templates feature. If you wish to quickly start with Pulse, you can use either of two templates:
- Prisma Pulse DB Only: Provides a fresh, pre-configured PostgreSQL database which you can use with Pulse.
- Prisma Pulse DB & App: Provides a pre-configured PostgreSQL database and a Pulse starter app.
Setup without using a template
You can run these queries in the Railway Database Query tab, using the railway cli, or any other way you might run queries on your database.
- Drop the Timescale extension:
DROP EXTENSION timescaledb;
- Set the
wal_level tological
:
ALTER SYSTEM SET wal_level = logical;
- Set the
max_replication_slots to20
:
ALTER SYSTEM SET max_replication_slots = 20;
- Set the
wal_keep_size to2048
:
ALTER SYSTEM SET wal_keep_size = 2048;
- Reload the PostgreSQL configuration:
SELECT pg_reload_conf();
Click on your database.
Navigate to the Settings tab.
Scroll down and click the Restart Database button.
2. Enable Pulse in a Cloud Project
Log into the Prisma Data Platform, create a new Cloud Project and enable Pulse for that new project.
3. Use Pulse in your application
We have created an example repository on GitHub to help you get started using Pulse. If you would like to start there, you can do so.
The following will show how you can utilize Pulse in an existing application. We will be adding Pulse to the hello-prisma example from our documentation.
3.1. Install the Pulse Prisma Client extension
In a project using Prisma Client, run the following command to install the Pulse extension:
$npm install @prisma/extension-pulse
Store your Cloud Projects API key in your .env file
The Pulse extension requires you to use a Cloud Projects API key.
You should have received an API key from the Cloud Projects dashboard when setting up your project.
In .env
, add a variable named PULSE_API_KEY
:
.env
1PULSE_API_KEY="YOUR-API-KEY"23# Example:4# PULSE_API_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcGlfa2V5IjoiNGMxNzM0MGItMmFhYy00MGMxLWE1ZDctNzYyNmRjNjg3NjM4IiwidGVuYW50X2lkIjoiY2VhZjE0NThkZGUyYzJmNTU0ZmNkNTI2MmFmOWY1ODljMWJiZmRhNDU0N2UxMjM1ODk3MGQ2MGI1ZjRlNTU0OCIsImludGVybmFsX3NlY3JldCI6ImM1ZTcxYjJhLTE0NzdawdwDliZS1hM2IzLTczODFkNDM5ZmEwZSJ9.wCUlghC_suFBr2vnk0q_5I8iRNRDyEQo0W9rnhf6mCw"
3.2. Create a Pulse-enabled Prisma Client
To use Pulse, you must extend Prisma Client with the Pulse extension. Add the following to extend your existing Prisma Client instance with the 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 }))
3.3. Create your first Pulse subscription
With the Pulse extension applied, you may now use Pulse's subscribe()
method on any model defined in your Prisma Schema to subscribe to data change events.
In the example below, a subscription is made on a user
table that listens for any change event on that table:
const prisma = new PrismaClient().$extends(withPulse({ apiKey: apiKey }))async function main() {const subscription = await prisma.user.subscribe({})if (subscription instanceof Error) {throw subscription}for await (const event of subscription) {console.log('just received an event:', event)}}main()
Refer to the API Reference section for more detail on the filtering options available to the subscribe()
method.