Getting started

Prerequisites

To participate in Pulse's Early Access program, you need to meet the following prerequisites:

  • A GitHub account.
  • Pulse requires Prisma Client version 4.16.1 or higher and version v0.2.2 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.

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.
  • Connect to the database using sslmode=disable if the database provider uses self-signed certificates.

1. Database setup

General database configuration

Required settings

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 on your PostgreSQL database. We suggest setting these values initially and adjusting them if necessary.

ALTER SYSTEM SET max_replication_slots = 20;
ALTER SYSTEM SET wal_keep_size = 2048;

Provider specific configuration

To learn about the database providers that Pulse supports, visit here.

Railway

offers an excellent . If you wish to quickly start with Pulse, you can use either of two templates:

  • : Provides a fresh, pre-configured PostgreSQL database which you can use with Pulse.
  • : Provides a pre-configured PostgreSQL database and a .
Setup without using a template

You can run these queries in the Railway Database Query tab, using the , or any other way you might run queries on your database.

  1. Drop the Timescale extension:
DROP EXTENSION timescaledb;
  1. Set the to logical:
ALTER SYSTEM SET wal_level = logical;
  1. Set the to 20:
ALTER SYSTEM SET max_replication_slots = 20;
  1. Set the to 2048:
ALTER SYSTEM SET wal_keep_size = 2048;
  1. Reload the PostgreSQL configuration:
SELECT pg_reload_conf();
  1. Click on your database.

  2. Navigate to the Deployments tab.

  3. Go into the three-dots menu on the latest deployment and click the Restart option.

SSL mode

As Railway uses a self-signed certificate, you have to use sslmode=disable with Pulse.

2. Enable Pulse in a project

Log into the , create a new project and enable Pulse for that new project.

An API key will be created after you enable and setup Pulse in your project.

3. Use Pulse in your application

We have created an 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 Pulse API key in your .env file

The Pulse extension requires you to use an API key.

You should have received an API key when you added Prisma Pulse to your project in the Platform Console.

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.