From f7f55ae96c98b5d9d07a34558d12193008285e87 Mon Sep 17 00:00:00 2001
From: Luan van der Westhuizen <6928171+luanvdw@users.noreply.github.com>
Date: Thu, 21 Mar 2024 14:16:03 +0200
Subject: [PATCH] feat: pulse getting started guide (#5738)
* 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 <64993082+ankur-arch@users.noreply.github.com>
---
content/400-pulse/200-getting-started.mdx | 76 +++++++++--------------
1 file changed, 29 insertions(+), 47 deletions(-)
diff --git a/content/400-pulse/200-getting-started.mdx b/content/400-pulse/200-getting-started.mdx
index 1f60b3d916..6f7fdcb8c1 100644
--- a/content/400-pulse/200-getting-started.mdx
+++ b/content/400-pulse/200-getting-started.mdx
@@ -16,42 +16,35 @@ toc: true
-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
-
-
-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.
-
-
-
-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
-💡 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
-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
@@ -72,55 +65,44 @@ const prisma = new PrismaClient().$extends(
-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.
-### 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()
```
-
-
-Refer to the [API Reference](/pulse/api-reference) section for more detail on the filtering options available to the `subscribe()` method.
-
-
+All done! You've successfully added Pulse to your application. Explore next steps to learn more.
-## Database setup
+## Next steps
-
+[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
+ },
+})
+```
-
+## 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.