Skip to main content

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 @prisma/extension-pulse 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​

[wal_level](https://www.postgresql.org/docs/current/runtime-config-wal.html)​

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](https://www.postgresql.org/docs/current/runtime-config-replication.html)​
ALTER SYSTEM SET max_replication_slots = 20;
[wal_keep_size](https://www.postgresql.org/docs/current/runtime-config-replication.html)​
ALTER SYSTEM SET wal_keep_size = 2048;

Provider specific configuration​

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

Railway​

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

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.

  1. Drop the Timescale extension:
DROP EXTENSION timescaledb;
  1. Set the [wal_level](https://www.postgresql.org/docs/current/runtime-config-wal.html) to logical:
ALTER SYSTEM SET wal_level = logical;
  1. Set the [max_replication_slots](https://www.postgresql.org/docs/current/runtime-config-replication.html) to 20:
ALTER SYSTEM SET max_replication_slots = 20;
  1. Set the [wal_keep_size](https://www.postgresql.org/docs/current/runtime-config-replication.html) to 2048:
ALTER SYSTEM SET wal_keep_size = 2048;
  1. Reload the PostgreSQL configuration:
SELECT pg_reload_conf();
2. Restart your database

  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 Prisma Data Platform, 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​

info

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 Pulse API key in your .env file​

The Pulse extension requires you to use an API key.

info

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:

PULSE_API_KEY="YOUR-API-KEY"

# Example:
# 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()
info

Refer to the API Reference section for more detail on the filtering options available to the subscribe() method.