Skip to content

Commit

Permalink
feat: pulse getting started guide (#5738)
Browse files Browse the repository at this point in the history 
* feat: misc changes

* -m

* Update content/400-pulse/200-getting-started.mdx

* Update content/400-pulse/200-getting-started.mdx

---------

Co-authored-by: Ankur Datta <[email protected]>
  • Loading branch information
@luanvdw @ankur-arch
luanvdw and ankur-arch authored Mar 21, 2024
1 parent 973bf5b commit f7f55ae
Showing 1 changed file with 29 additions and 47 deletions.
76 changes: 29 additions & 47 deletions content/400-pulse/200-getting-started.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,42 +16,35 @@ toc: true

</Admonition>

You'll need the following to integrate Prisma Pulse into your application;
You'll need the following to integrate Pulse into your application;

- Prisma Data Platform workspace
- [Prisma Client](/orm/prisma-client) version `4.16.1` or higher and [`@prisma/extension-pulse`](https://www.npmjs.com/package/@prisma/extension-pulse) version `v1.0.1` or higher.
- A publicly accessible PostgreSQL (version 12+) database with [logical replication](https://www.postgresql.org/docs/current/logical-replication-quick-setup.html) enabled.
- Learn how to enable logical replication [here](/pulse/database-setup/general-database-instructions#enable-logical-replication)
- [Prisma Data Platform workspace](https://console.prisma.io)
- [Prisma Client](/orm/prisma-client) version `4.16.1` or higher and [`@prisma/extension-pulse`](https://www.npmjs.com/package/@prisma/extension-pulse) version `1.0.1` or higher.
- A publicly accessible PostgreSQL (version 12+) database with [logical replication](https://www.postgresql.org/docs/current/logical-replication-quick-setup.html) enabled. View our [setup guide](/pulse/database-setup/general-database-instructions#enable-logical-replication) on configuring logical replication for your database.

## 1. Enable Pulse

Access your Prisma Data Platform project and enable Prisma Pulse within an environment. We'll connect to your database and verify connectivity during setup.
Navigate to your Prisma Data Platform project, choose an environment, and enable Pulse. We'll connect to your database and verify connectivity during setup.

> Once enabled, you'll be prompted to create an API key that you'll use in your extended Prisma Client to authenticate requests. Store this API key in your application's `.env` file:
> Once enabled, you'll be prompted to generate an API key that you'll use in your extended Prisma Client to authenticate requests. Store this API key in your application's `.env` file:
>
> ```env file=.env
> PULSE_API_KEY="your_lengthy_secure_pulse_api_key"
> PULSE_API_KEY="your_secure_pulse_api_key"
> ```
## 2. Add Pulse to your application
<Admonition type="info">
We have created an [example repository](https://github.com/prisma/pulse-starter) on GitHub to help you get started using Prisma Pulse. If you would like to start there, you can do so.
</Admonition>
We'll be adding Prisma Pulse to the [hello-prisma](/getting-started/setup-prisma/start-from-scratch/relational-databases-typescript-postgresql) starter project from our documentation.
With Pulse enabled, proceed with these steps to integrate Pulse into your application. You can also utilize our [example repository](https://github.com/prisma/pulse-starter) on GitHub as a reference guide.
### 2.1. Install the Prisma Pulse Client extension
### 2.1. Install the Pulse Client extension
<Admonition>
💡 Prisma Pulse requires [Prisma Client](/orm/prisma-client) version `4.16.1` or higher and [`@prisma/extension-pulse`](https://www.npmjs.com/package/@prisma/extension-pulse) `v0.2.3` or higher
💡 Pulse requires [Prisma Client](/orm/prisma-client) version `4.16.1` or higher and [`@prisma/extension-pulse`](https://www.npmjs.com/package/@prisma/extension-pulse) version `1.0.1` or higher
</Admonition>
Install the latest version of Prisma Client and Pulse Prisma Client extension
Install the latest version of Prisma Client and the Pulse Client extension
```bash
npm install @prisma/client@latest @prisma/extension-pulse@latest
Expand All @@ -72,55 +65,44 @@ const prisma = new PrismaClient().$extends(

<Admonition type="info">

You should have received an **API key** when you added Prisma Pulse to your environment in the Platform Console.
You stored this API key in your .env file after [enabling Pulse](#1-enable-pulse). If needed, you can navigate to your respective project environment and generate a new API key.

</Admonition>

### 2.3. Create your first Prisma Pulse subscription
### 2.3. Create your first Pulse subscription

With the Prisma Pulse extension applied, you may now use Prisma Pulse's `subscribe()` method on any model defined in your Prisma Schema to subscribe to data change events.
With the Pulse extension applied, you can 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:
In the below example, a subscription is made to a `notification` model that listens for _any_ change event on that table:

```ts
const prisma = new PrismaClient().$extends(withPulse({ apiKey: apiKey }))

async function main() {
const subscription = await prisma.user.subscribe({})

if (subscription instanceof Error) {
throw subscription
}

// Example: 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)
const subscription = await prisma.notification.subscribe()

for await (const event of subscription) {
console.log('just received an event:', event)
console.log('just received a notification:', event)
}
}

main()
```

<Admonition type="info">

Refer to the [API Reference](/pulse/api-reference) section for more detail on the filtering options available to the `subscribe()` method.

</Admonition>
All done! You've successfully added Pulse to your application. Explore next steps to learn more.

## Database setup
## Next steps

<Admonition>
[Navigate to the API section](/pulse/api-reference) to explore available filtering options for Pulse's `subscribe()` method.

Prisma Pulse requires a publicly accessible PostgreSQL (version 12+) database with logical replication enabled.
```ts
const subscription = await prisma.notification.subscribe({
create: {
userId: 123, // subscribe to all notifications created for the user with ID 123
},
})
```

</Admonition>
## Need help?

To setup your database to work with Prisma Pulse, refer to the [database setup page](/pulse/database-setup).
Reach out to us in the `#help-and-questions` channel on our [Discord](https://pris.ly/discord), or connect with our community to see how others are using Pulse.

0 comments on commit f7f55ae

Please sign in to comment.