@prisma/extension-pulse v1.0.2

Pulse Prisma Client extension

This is the package for the Prisma Client extension that enables usage of Prisma Pulse.

Prisma Pulse is a managed change stream service that simplifies real-time application development. It enables developers to subscribe to database change events in a type-safe manner using their Prisma Client.

It is part of the Prisma ecosystem, alongside other tools such as:

• Prisma ORM: Next-generation Node.js and TypeScript ORM, supporting PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, CockroachDB, and MongoDB.
• Prisma Accelerate: Global database cache with scalable connection pooling.

Prisma is leading Data DX, a philosophy that promotes simplicity in data-driven application development. Learn more on the Data DX manifesto.

Getting started

Resources

You can explore Pulse with the following resources:

• Get started
• Documentation
• Prisma Data Platform
• Examples
  • Starter project
  • End-to-end chat application

Using Pulse

1. Enable Pulse

Log into the Prisma Data Platform and enable Pulse for your project.

2. Add Pulse to your application

Extend your Prisma Client instance with the Pulse extension:

import { PrismaClient } from '@prisma/client'
import { withPulse } from '@prisma/extension-pulse'

const prismaWithPulse = new PrismaClient()
  .$extends(
    withPulse({
      apiKey: process.env['PULSE_API_KEY']
    })
  )

export prismaWithPulse

3. Subscribe to real-time database events

Use the subscribe() method to wait for new database events:

import { prismaWithPulse } from "./prisma";

async function main() {
  // Subscribe to new events on the `message` table
  const subscription = await prismaWithPulse.message.subscribe({});

  // Set a timeout to the subscription after 60 seconds.
  // Explicitly stopping the subscriptions and closing the connection is needed
  // to not exhaust the limited number of subscriptions allowed per table.

  setTimeout(() => {
    console.log("Stopping the subscription.");
    subscription.stop();
  }, 60000);

  // Waiting loop that prints new events when something changes in the database
  for await (const event of subscription) {
    console.log("new event:", event); // 'create', 'update', 'delete'
  }
}

main();

Important

Using "moduleResolution": "bundler"

The Prisma Pulse extension offers separate implementations tailored for various runtimes, such as Node.js and Cloudflare Workers. If you're using bundler moduleResolution in your TSConfig, you must also explicitly set customConditions to either node or workerd depending on your target runtime. This will instruct TypeScript to match the correct type definitions of the Prisma Pulse extension, as well as any other packages that expose multiple entrypoints.

// tsconfig.json
{
  "compilerOptions": {
    // ...other options
    "target": "es2022",
    "moduleResolution": "bundler",
    "customConditions": ["workerd"] // or "node"
  }
}