prisma / pulse-starter

A Pulse starter project. To be used inside of a railway.app template, locally, or with another Pulse-ready database.

Prisma Pulse starter project

This repository has been created to help you get started with Pulse. You will be able to use this project with any Pulse-ready PostgreSQL database. This project comes with a basic schema.prisma file as well as a Pulse subscription found in the index.ts file.

Prerequisites

To successfully run the project, you will need the following:

• The connection string of a Pulse-compatible database (if you don't have one yet, you can configure your database following the instructions in our docs or use a Railway template)
• A Pulse API key which you can get by enabling Pulse in a project in your Prisma Data Platform account

Getting started

1. Clone the respository

Clone the repository, navigate into it and install dependencies:

git clone https://github.com/prisma/pulse-starter.git
cd pulse-starter
npm install

2. Create and fill out a .env file

Rename the existing .env.example to .env:

mv .env.example .env

Now go into the .env file and update the DATABASE_URL and PULSE_API_KEY environment variables:

DATABASE_URL="postgres://postgres:password@host:PORT/database_name" 
PULSE_API_KEY="your_secure_pulse_api_key"

• DATABASE_URL: The connection string to your database.
• PULSE_API_KEY: Reference the Environment API Keys section in our documentation to learn how get an API key for your Pulse project.

3. Run the database migration

The prisma/schema.prisma contains three models based on our hello-prisma example project:

npx prisma migrate dev --name init

4. Start the Pulse subscription

Run the script that contains the code to subscribe to database events:

npx ts-node index.ts

This will run a basic subscription on the User table. The code can be found in the index.ts file. To learn more about the Pulse API and how to use it, check out our documentation.

Pulse user table subscription

async function main() {
  const subscription = await prisma.user.stream();

  if (subscription instanceof Error) {
    throw subscription;
  }

  for await (const event of subscription) {
    console.log("just received an event:", event);
  }
}

5. Test the subscription

The following instructions uses Prisma Studio to create a new record in the User table. However, you can use any other method to write to the User table (e.g. a SQL client like psql or TablePlus) in order to trigger a database change event in Pulse.

1. Start Prisma Studio in a new terminal: npx prisma studio

2. Add a new record to the User table from Prisma Studio.

3. Return to your terminal where you ran the npx ts-node index.ts command.

4. If everything is set up properly you will see an output that is similar to the following.

   {
     "action": "create",
     "created": {
       "id": 1,
       "email": "[e-mail]",
       "name": "test"
     }
   }

Deployment

You can also deploy this project on Railway by following the instructions in our docs.

Resources

• Prisma Pulse examples
• Pulse documentation
• Pulse GA announcement blog post