Getting started with Pulse

/ Pulse

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 to logical.
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

1. Change the PostgreSQL database settings

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 to logical:


ALTER SYSTEM SET wal_level = logical;

Set the max_replication_slots to 20:


ALTER SYSTEM SET max_replication_slots = 20;

Set the wal_keep_size to 2048:


ALTER SYSTEM SET wal_keep_size = 2048;

Reload the PostgreSQL configuration:


SELECT pg_reload_conf();

2. Restart your database

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"
2
3# 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.

Was this helpful?

Edit this page on GitHub

Getting started