diff --git a/content/200-orm/050-overview/500-databases/860-cockroachdb.mdx b/content/200-orm/050-overview/500-databases/840-cockroachdb.mdx similarity index 100% rename from content/200-orm/050-overview/500-databases/860-cockroachdb.mdx rename to content/200-orm/050-overview/500-databases/840-cockroachdb.mdx diff --git a/content/200-orm/100-prisma-schema/20-data-model/10-models.mdx b/content/200-orm/100-prisma-schema/20-data-model/10-models.mdx index 62418d990c..e13e55d298 100644 --- a/content/200-orm/100-prisma-schema/20-data-model/10-models.mdx +++ b/content/200-orm/100-prisma-schema/20-data-model/10-models.mdx @@ -395,7 +395,7 @@ model Post { model Comment { id Int // Other fields - Post Post? @relation(fields: [postId], references: [id]) // A comment can have one post + post Post? @relation(fields: [postId], references: [id]) // A comment can have one post postId Int? } ``` @@ -413,7 +413,7 @@ model Post { model Comment { id String @id @default(auto()) @map("_id") @db.Objectid // Other fields - Post Post? @relation(fields: [postId], references: [id]) // A comment can have one post + post Post? @relation(fields: [postId], references: [id]) // A comment can have one post postId String? @db.ObjectId } ``` diff --git a/content/200-orm/200-prisma-client/100-queries/056-aggregation-grouping-summarizing.mdx b/content/200-orm/200-prisma-client/100-queries/056-aggregation-grouping-summarizing.mdx index 8c039d9462..6b59303b93 100644 --- a/content/200-orm/200-prisma-client/100-queries/056-aggregation-grouping-summarizing.mdx +++ b/content/200-orm/200-prisma-client/100-queries/056-aggregation-grouping-summarizing.mdx @@ -329,7 +329,9 @@ Both `distinct` and `groupBy` group records by one or more unique field values. ## Count -Use [`count`](/orm/reference/prisma-client-reference#count) to count the number of records or non-`null` field values. The following example query counts all users: +### Count records + +Use [`count()`](/orm/reference/prisma-client-reference#count) to count the number of records or non-`null` field values. The following example query counts all users: ```ts const userCount = await prisma.user.count() @@ -337,12 +339,9 @@ const userCount = await prisma.user.count() ### Count relations -The ability to count relations is available in version [3.0.1](https://github.com/prisma/prisma/releases/3.0.1) and later. - -**For versions before 3.0.1**
-You need to add the [preview feature](/orm/reference/preview-features/client-preview-features#enabling-a-prisma-client-preview-feature) `selectRelationCount` and then run `prisma generate`. +This feature is generally available in version [3.0.1](https://github.com/prisma/prisma/releases/3.0.1) and later. To use this feature in versions before 3.0.1 the [Preview feature](/orm/reference/preview-features/client-preview-features#enabling-a-prisma-client-preview-feature) `selectRelationCount` will need to be enabled. @@ -380,7 +379,7 @@ The `_count` parameter: - Can be used inside a top-level `include` _or_ `select` - Can be used with any query that returns records (including `delete`, `update`, and `findFirst`) - Can return [multiple relation counts](#return-multiple-relation-counts) -- From version 4.3.0, can [filter relation counts](#filter-the-relation-count) +- Can [filter relation counts](#filter-the-relation-count) (from version 4.3.0) #### Return a relations count with include @@ -415,7 +414,7 @@ const usersWithCount = await prisma.user.findMany({ #### Return a relations count with `select` -The following query uses `select` to return each user's post count and no other fields: +The following query uses `select` to return each user's post count _and no other fields_: diff --git a/content/200-orm/200-prisma-client/100-queries/090-raw-database-access/050-raw-queries.mdx b/content/200-orm/200-prisma-client/100-queries/090-raw-database-access/050-raw-queries.mdx index 89787f373f..be7748b967 100644 --- a/content/200-orm/200-prisma-client/100-queries/090-raw-database-access/050-raw-queries.mdx +++ b/content/200-orm/200-prisma-client/100-queries/090-raw-database-access/050-raw-queries.mdx @@ -28,6 +28,8 @@ For relational databases, Prisma Client exposes four methods that allow you to s - `$queryRawUnsafe` to return actual records (for example, using `SELECT`) using a raw string. **Potential SQL injection risk** - `$executeRawUnsafe` to return a count of affected rows (for example, after an `UPDATE` or `DELETE`) using a raw string. **Potential SQL injection risk** +> **Note**: All methods in the above list can only run **one** query at a time. You cannot append a second query - for example, calling any of them with `select 1; select 2;` will not work. + ### $queryRaw `$queryRaw` returns actual database records. For example, the following `SELECT` query returns all fields for each record in the `User` table: @@ -323,8 +325,6 @@ $executeRaw(query: TemplateStringsArray | Prisma.Sql, ...values: an The `$executeRawUnsafe` method allows you to pass a raw string (or template string) to the database. Like `$executeRaw`, it does **not** return database records, but returns the number of rows affected. -> **Note**: `$executeRawUnsafe` can only run **one** query at a time. You cannot append a second query - for example, adding `DROP bobby_tables` to the end of an `ALTER`. - If you use this method with user inputs (in other words, `SELECT * FROM table WHERE columnx = ${userInput}`), then you open up the possibility for SQL injection attacks. SQL injection attacks can expose your data to modification or deletion.

@@ -561,8 +561,6 @@ Prisma Client mitigates the risk of SQL injection in the following ways: $executeRaw`...` // Tagged template ``` -- `$executeRaw` can only run **one** query at a time. You cannot append a second query - for example, adding `DROP bobby_tables` to the end of an `ALTER`. - If you cannot use tagged templates, you can instead use [`$queryRawUnsafe`](/orm/prisma-client/queries/raw-database-access/raw-queries#queryrawunsafe) or [`$executeRawUnsafe`](/orm/prisma-client/queries/raw-database-access/raw-queries#executerawunsafe) but **be aware that your code may be vulnerable to SQL injection**. #### ⚠️ String concatenation diff --git a/content/200-orm/200-prisma-client/500-deployment/550-deploy-database-changes-with-prisma-migrate.mdx b/content/200-orm/200-prisma-client/500-deployment/550-deploy-database-changes-with-prisma-migrate.mdx index 0bd45a44fd..d797f1a84d 100644 --- a/content/200-orm/200-prisma-client/500-deployment/550-deploy-database-changes-with-prisma-migrate.mdx +++ b/content/200-orm/200-prisma-client/500-deployment/550-deploy-database-changes-with-prisma-migrate.mdx @@ -15,7 +15,7 @@ npx prisma migrate deploy This guide **does not apply for MongoDB**.
-Instead of `migrate deploy`, [`db push`](/orm/prisma-migrate/workflows/prototyping-your-schema) is used for [MongoDB](/orm/overview/databases/mongodb)). +Instead of `migrate deploy`, [`db push`](/orm/prisma-migrate/workflows/prototyping-your-schema) is used for [MongoDB](/orm/overview/databases/mongodb). diff --git a/content/200-orm/500-reference/050-prisma-client-reference.mdx b/content/200-orm/500-reference/050-prisma-client-reference.mdx index e205358b76..ee5c9f3e26 100644 --- a/content/200-orm/500-reference/050-prisma-client-reference.mdx +++ b/content/200-orm/500-reference/050-prisma-client-reference.mdx @@ -2775,10 +2775,11 @@ A nested `createMany` query adds a new set of records to a parent record. See: [ #### Remarks - `createMany` is available as a nested query when you `create` (`prisma.user.create(...)`) a new parent record or `update` (`prisma.user.update(...)`) an existing parent record. -- Available in the context of a has-many relation - for example, you can `prisma.user.create(...)` a user and use a nested `createMany` to create multiple posts (posts have one user). -- **Not** available in the context of a many-to-many relation - for example, you **cannot** `prisma.post.create(...)` a post and use a nested `createMany` to create categories (many posts have many categories). -- Does not support nesting additional relations - you cannot nest an additional `create` or `createMany`. -- Allows setting foreign keys directly - for example, setting the `categoryId` on a post. +- Available in the context of a one-to-many relation — for example, you can `prisma.user.create(...)` a user and use a nested `createMany` to create multiple posts (posts have one user). +- **Not** available in the context of a many-to-many relation — for example, you **cannot** `prisma.post.create(...)` a post and use a nested `createMany` to create categories (many posts have many categories). +- Does not support nesting additional relations — you cannot nest an additional `create` or `createMany`. +- Allows setting foreign keys directly — for example, setting the `categoryId` on a post. +- Nested `createMany` is not supported by SQLite. > You can use a nested `create` _or_ a nested `createMany` to create multiple related records - [each technique pros and cons](/orm/prisma-client/queries/relation-queries#create-a-single-record-and-multiple-related-records) . diff --git a/content/200-orm/500-reference/250-error-reference.mdx b/content/200-orm/500-reference/250-error-reference.mdx index 6383e642fe..f0f038c7f2 100644 --- a/content/200-orm/500-reference/250-error-reference.mdx +++ b/content/200-orm/500-reference/250-error-reference.mdx @@ -489,3 +489,38 @@ The engine failed to start. For example, it couldn't establish a connection to t #### P6009 (ResponseSizeLimitExceeded) The global response size limit of Accelerate has been exceeded. You can find the limit [here](/accelerate/limitations#response-size-limit). + +### Prisma Pulse + +Prisma Pulse-related errors start with P61xx. + +#### P6100 (ServerError) – HTTP Status 500 + +An unexpected server error occurred. +This can happen due to a technical issue within the Prisma Pulse or its infrastructure. +For any incidents related to Prisma Pulse, you can refer to our status page [here](https://www.prisma-status.com/) and reach out to our support team through one of our available [channels](https://www.prisma.io/docs/platform/support) to report your issue. + +#### P6101 (DatasourceError) – HTTP Status 400 + +Reasons: + +1. The datasource is not reachable by Prisma Pulse. The Console will validate the connection when enabling Pulse to reduce the likelihood of this error. However, the datasource may become unavailable after the configuration step, resulting in this error. +2. The datasource is reachable, but did not meet the requirements for Prisma Pulse. The Console will validate the configuration when enabling Pulse to reduce the likelihood of this error. However, the datasource may change after the configuration step, resulting in this error. + +#### P6102 (Unauthorized) – HTTP Status 400 + +The API key is invalid. + +#### P6103 (ProjectDisabledError) – HTTP Status 400 + +Prisma Pulse is not enabled for the configured API key. + +#### P6104 (AccountHoldError) – HTTP Status 400 + +Your Prisma Data Platform account has been blocked, potentially due to exceeding the usage limit included in your current plan. Please review the error message for further information. + +If you require further assistance, please get in touch with us via one of our support [channels](https://www.prisma.io/docs/platform/support). + +#### P6105 (VersionNotSupported) – HTTP Status 400 + +The Prisma version of the project is not compatible with Prisma Pulse. diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/400-nextjs-prisma-client-dev-practices.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/400-nextjs-prisma-client-dev-practices.mdx index 4610c7ba75..13fe408922 100644 --- a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/400-nextjs-prisma-client-dev-practices.mdx +++ b/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/400-nextjs-prisma-client-dev-practices.mdx @@ -28,14 +28,14 @@ const prismaClientSingleton = () => { } declare global { - var prisma: undefined | ReturnType + var prismaGlobal: undefined | ReturnType } -const prisma = globalThis.prisma ?? prismaClientSingleton() +const prisma = globalThis.prismaGlobal ?? prismaClientSingleton() export default prisma -if (process.env.NODE_ENV !== 'production') globalThis.prisma = prisma +if (process.env.NODE_ENV !== 'production') globalThis.prismaGlobal = prisma ``` You can extend Prisma Client using a Prisma Client extension by appending the `$extends` client method when instantiating Prisma Client as follows: diff --git a/content/400-pulse/100-what-is-pulse.mdx b/content/400-pulse/100-what-is-pulse.mdx index 0c81c2daa1..e196381dcf 100644 --- a/content/400-pulse/100-what-is-pulse.mdx +++ b/content/400-pulse/100-what-is-pulse.mdx @@ -8,16 +8,31 @@ toc: true -[Pulse](https://www.prisma.io/data-platform/pulse) is a managed [change data capture (CDC)](https://en.wikipedia.org/wiki/Change_data_capture) service that captures change events from your database and delivers them instantly to your applications. With Pulse, you can quickly build real-time applications in a type-safe manner using [Prisma Client](/orm/prisma-client). +[Prisma Pulse](https://www.prisma.io/data-platform/pulse) is managed database-event infrastructure that captures and distributes your database events to your application. It simplifies subscribing to type-safe data changes with an extended [Prisma Client](/orm/prisma-client) to power real-time functionality. + + + +## How Prisma Pulse works + +Prisma Pulse leverages Change Data Capture (CDC) to efficiently observe and capture database changes as they occur. By monitoring the database's transaction log, Prisma Pulse identifies change events like inserts, updates, and deletes without impacting the database's performance. + +The captured events are processed, evaluated, and swiftly distributed to relevant client subscriptions ensuring your applications stay synchronized with the latest database state. + +This eliminates the need for complex polling or manual data synchronization, saving you development time and effort. ![What is Pulse](./images/what-is-pulse.png) - +## What you can build with Prisma Pulse -Pulse is currently in [Early Access](/platform/maturity-levels#early-access). Although we already have high confidence in it, the nature of an Early Access product is that significant iterations might happen at any time. Therefore, we advise against using it in a system that requires stability.

+Prisma Pulse can power real-time functionality like chat, notifications, data broadcast, data synchronization, and more. It's ideal for ensuring data consistency in distributed systems, enhancing real-time user experiences. -We strongly recommend evaluating Pulse with a dedicated database instance that is exclusively used for Pulse and where downtime and data loss would be acceptable. Prisma assumes no responsibility for downtime or data loss. +![Prisma Pulse use-cases](./images/pulse-usecase.png) - +## Examples - +Here are a few example projects using Prisma Pulse: + +| Project | Description | +| :--------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| [pulse-starter](https://github.com/prisma/pulse-starter) | General Pulse starter project. | +| [pulse-resend-demo](https://github.com/prisma/pulse-resend-demo) | Optimize your onboarding with Pulse by triggering welcome emails via Resend for new user sign-ups. | diff --git a/content/400-pulse/200-getting-started.mdx b/content/400-pulse/200-getting-started.mdx index 0a9e18fb9f..7747129f4f 100644 --- a/content/400-pulse/200-getting-started.mdx +++ b/content/400-pulse/200-getting-started.mdx @@ -1,8 +1,8 @@ --- title: 'Getting started' -metaTitle: 'Getting started with Pulse' -metaDescription: 'Learn how to get up and running with Pulse.' -tocDepth: 3 +metaTitle: 'Getting started with Prisma Pulse' +metaDescription: 'Learn how to get up and running with Prisma Pulse.' +tocDepth: 4 toc: true --- @@ -10,157 +10,50 @@ toc: true ## Prerequisites -To participate in Pulse's Early Access program, you need to meet the following prerequisites: +You'll need the following to integrate Prisma Pulse into your application; -- A GitHub account. -- 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 `v0.2.3` 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. +- 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 `v0.2.3` 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) -You will also need a database with the following configurations: +## 1. Enable Pulse -- PostgreSQL version 12+. -- Ensure your database is publicly accessible. -- [Set the `wal_level` setting in PostgreSQL to `logical`](/pulse/getting-started#wal_level). -- 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. _This is a Prisma Pulse [Early Access](/platform/maturity-levels#early-access) limitation that will be lifted before Prisma Pulse [General Availability](platform/maturity-levels#general-availability)_. +Access your Prisma Data Platform project and enable Prisma Pulse within an environment. We'll connect to your database and verify connectivity during setup. -## 1. Database 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: +> +> ```env file=.env +> PULSE_API_KEY="your_lengthy_secure_pulse_api_key" +> ``` -### 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. - -```sql -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](https://www.postgresql.org/docs/current/wal-intro.html) 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) - -```sql -ALTER SYSTEM SET max_replication_slots = 20; -``` - -##### [wal_keep_size](https://www.postgresql.org/docs/current/runtime-config-replication.html) - -```sql -ALTER SYSTEM SET wal_keep_size = 2048; -``` - -### Provider specific configuration - -To learn about the database providers that Pulse supports, visit [here](/pulse/faq#what-database-providers-are-supported-with-pulse). - -#### Railway - -[Railway.app](https://railway.app) offers an excellent [templates feature](https://railway.app/templates). If you wish to quickly start with Pulse, you can use either of two templates: - -- [Prisma Pulse DB Only](https://railway.app/template/pulse-pg): Provides a fresh, pre-configured PostgreSQL database which you can use with Pulse. -- [Prisma Pulse DB & App](https://railway.app/template/pulse-starter): Provides a pre-configured PostgreSQL database and a [Pulse starter app](https://github.com/prisma/pulse-starter). - -##### 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](https://docs.railway.app/databases/postgresql), or any other way you might run queries on your database. - -1. Set the [wal_level](https://www.postgresql.org/docs/current/runtime-config-wal.html) to `logical`: - -```sql -ALTER SYSTEM SET wal_level = logical; -``` - -2. Set the [max_replication_slots](https://www.postgresql.org/docs/current/runtime-config-replication.html) to `20`: - -```sql -ALTER SYSTEM SET max_replication_slots = 20; -``` - -3. Set the [wal_keep_size](https://www.postgresql.org/docs/current/runtime-config-replication.html) to `2048`: - -```sql -ALTER SYSTEM SET wal_keep_size = 2048; -``` - -4. Reload the PostgreSQL configuration: - -```sql -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`](/orm/overview/databases/postgresql#configuring-an-ssl-connection) with Pulse. _This is a Prisma Pulse [Early Access](/platform/maturity-levels#early-access) limitation that will be lifted before Prisma Pulse [General Availability](platform/maturity-levels#general-availability)_. - -## 2. Enable Pulse in a project - -Log into the [Prisma Data Platform](https://console.prisma.io/login), 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](/platform/concepts/projects). - -## 3. Use Pulse in your application +## 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 Pulse. If you would like to start there, you can do so. +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. -The following will show how you can utilize Pulse in an existing application. We will be adding Pulse to the [hello-prisma](/getting-started/setup-prisma/start-from-scratch/relational-databases-typescript-postgresql) example from our documentation. - -### 3.1. Install the Pulse Prisma Client extension +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. -In a project using [Prisma Client](/orm/prisma-client), run the following command to install the Pulse extension: - -```terminal -npm install @prisma/extension-pulse -``` +### 2.1. Install the Prisma Pulse Client extension -### Store your Pulse API key in your .env file + -The Pulse extension requires you to use an API key. - - - -You should have received an API key when you added Prisma Pulse to your project in the Platform Console. +💡 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 -In `.env`, add a variable named `PULSE_API_KEY`: - -```env file=.env -PULSE_API_KEY="YOUR-API-KEY" +Install the latest version of Prisma Client and Pulse Prisma Client extension -# Example: -# PULSE_API_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcGlfa2V5IjoiNGMxNzM0MGItMmFhYy00MGMxLWE1ZDctNzYyNmRjNjg3NjM4IiwidGVuYW50X2lkIjoiY2VhZjE0NThkZGUyYzJmNTU0ZmNkNTI2MmFmOWY1ODljMWJiZmRhNDU0N2UxMjM1ODk3MGQ2MGI1ZjRlNTU0OCIsImludGVybmFsX3NlY3JldCI6ImM1ZTcxYjJhLTE0NzdawdwDliZS1hM2IzLTczODFkNDM5ZmEwZSJ9.wCUlghC_suFBr2vnk0q_5I8iRNRDyEQo0W9rnhf6mCw" +```bash +npm install @prisma/client@latest @prisma/extension-pulse@latest ``` -### 3.2. Create a Pulse-enabled Prisma Client +### 2.2. Extend your Prisma Client instance with the Pulse extension -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: +Add the following to extend your existing Prisma Client instance with the Prisma Pulse extension: ```ts import { PrismaClient } from '@prisma/client' @@ -171,9 +64,15 @@ const prisma = new PrismaClient().$extends( ) ``` -### 3.3. Create your first Pulse subscription + + +You should have received an **API key** when you added Prisma Pulse to your environment in the Platform Console. + + -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. +### 2.3. Create your first Prisma 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. In the example below, a subscription is made on a `user` table that listens for _any_ change event on that table: @@ -209,3 +108,13 @@ main() Refer to the [API Reference](/pulse/api-reference) section for more detail on the filtering options available to the `subscribe()` method. + +## Database setup + + + +Prisma Pulse requires a publicly accessible PostgreSQL (version 12+) database with logical replication enabled. + + + +To setup your database to work with Prisma Pulse, refer to the [database setup page](/pulse/database-setup). diff --git a/content/400-pulse/250-database-setup/100-general-database-instructions.mdx b/content/400-pulse/250-database-setup/100-general-database-instructions.mdx new file mode 100644 index 0000000000..b7d70487ee --- /dev/null +++ b/content/400-pulse/250-database-setup/100-general-database-instructions.mdx @@ -0,0 +1,186 @@ +--- +title: 'General database instructions' +metaTitle: 'Prisma Pulse: General database instructions' +metaDescription: 'Instructions to use your database with Prisma Pulse' +tocDepth: 3 +toc: true +--- + + + +Prepare your database to work with Pulse. + + + +Prisma Pulse requires a publicly accessible PostgreSQL (**version 12+**) database with logical replication enabled. To configure specific database providers for Prisma Pulse, visit [here](/pulse/database-setup#provider-specific-instructions). + + + + + +## Database Replication + +Database replication is the process of creating copies of a database and storing them across various on-premises or cloud destinations. Prisma Pulse uses logical replication to monitor your database for changes. + +### Enable logical replication + +##### [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. + +```sql +ALTER SYSTEM SET wal_level = logical; +``` + +You will need to restart the database after changing this setting. + +##### Optional settings + +###### [wal_keep_size](https://www.postgresql.org/docs/current/runtime-config-replication.html) + +Setting `wal_keep_size` increases the memory usage of the [write-ahead log](https://www.postgresql.org/docs/current/wal-intro.html) on your PostgreSQL database. + +We recommend setting a value for `wal_keep_size` tailored to your database's storage capacity. This ensures smooth operation of both your database and Prisma Pulse. + + + +We suggest setting these values initially and adjusting them if necessary. + + + +```sql +ALTER SYSTEM SET wal_keep_size = 2048; +``` + +###### [max_replication_slots](https://www.postgresql.org/docs/current/runtime-config-replication.html) + +Prisma Pulse only needs one replication slot available. You can set the `max_replication_slots` if you have other replications in use. + + + +We suggest setting these values initially and adjusting them if necessary. + + + +```sql +ALTER SYSTEM SET max_replication_slots = 20; +``` + +###### [REPLICA IDENTITY](https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-REPLICA-IDENTITY) + +To get the **before** values of **all fields** in the record for some events, you must set `REPLICA IDENTITY` to `FULL` on the table(s) you want to get field values for. If this is not configured, defining a filter for those events will only be possible on the primary key. + +For example, running the following SQL command will set the `REPLICA IDENTITY` to `FULL` on a table named `User`: + +```sql +ALTER TABLE public."User" REPLICA IDENTITY FULL; +``` + +### Manage your own publication slot + +If you want to enable replication for *specific models* or use a database provider that restricts superuser access for Prisma Pulse our advanced setup allows you to configure your own publication slot and use it to enable Pulse. + +#### Creating a publication slot + +You can create publications in the following ways below depending on the version of your PostgreSQL database. + +
+ +Publication for all models. + +```sql +CREATE PUBLICATION $PUBLICATION_NAME FOR ALL TABLES; +``` + +
+ +
+ +Publication for specific fields. + +For example, create a publication that publishes all changes for table `users`, but replicates only columns `user_id` and `firstname`: + +```sql + CREATE PUBLICATION users_filtered FOR TABLE users (user_id, firstname); +``` + +
+ +
+ +Publication for specific models. + +For example, create a publication that publishes all changes in two tables: + +```sql +CREATE PUBLICATION user_and_department_publication FOR TABLE users, departments; +``` + +
+ +
+ +Publication for a model with a `WHERE` clause on it’s fields. + +For example, create a publication that publishes all changes from active `departments`: + +```sql +CREATE PUBLICATION active_departments FOR TABLE departments WHERE (active IS TRUE); +``` + +
+ +
+ +Publication based on DML operations.{' '} + +For example, create a publication that only publishes `INSERT` operations in one table: + +```sql +CREATE PUBLICATION insert_only FOR TABLE departments +WITH (publish = 'insert'); +``` + +> `publish` (`string`) +> +> This parameter determines which DML operations will be published by the new publication to the subscribers. The value is comma-separated list of operations. The allowed operations are `insert`, `update`, `delete`, and `truncate`. The default is to publish all actions, and so the default value for this option is `'insert, update, delete, truncate'`. + +You can learn more about the PostgreSQL's `CREATE PUBLICATION`, supported versions and see more examples [here](https://www.postgresql.org/docs/current/sql-createpublication.html). + +
+ +#### Submit your publication slot + +You can submit the publication name in the [Platform console](https://console.prisma.io/), before enabling Prisma Pulse: + +1. To view your [publications](https://www.postgresql.org/docs/current/view-pg-publication-tables.html), execute: + + ```sql + SELECT * FROM pg_publication_tables; + ``` + +2. Then you can submit the desired publication name in the Platform console: + + ![](../images/replication-slot-submission.png) + +#### Removing publications + +If you are managing your replications independently and choose to disable Prisma Pulse for a particular environment, you can refer to the following SQL queries to remove your publications. + +1. To delete a publication: + + ```sql + DROP PUBLICATION IF EXISTS "$PUBLICATION_SLOT_NAME"; + ``` + +2. View your [publications](https://www.postgresql.org/docs/current/view-pg-publication-tables.html): + + ```sql + SELECT * FROM pg_publication_tables; + ``` + + + +💡 To configure specific database providers for Prisma Pulse, visit [here](/pulse/database-setup#provider-specific-instructions). + + diff --git a/content/400-pulse/250-database-setup/200-aws-rds.mdx b/content/400-pulse/250-database-setup/200-aws-rds.mdx new file mode 100644 index 0000000000..d0a64ceb93 --- /dev/null +++ b/content/400-pulse/250-database-setup/200-aws-rds.mdx @@ -0,0 +1,33 @@ +--- +title: 'AWS RDS' +metaTitle: 'Prisma Pulse: AWS RDS' +metaDescription: 'Instructions to use AWS RDS with Prisma Pulse' +tocDepth: 3 +toc: true +--- + + + +You have to enable logical replication on AWS RDS to make it compatible with Prisma Pulse. + + + +## Enable logical replication on AWS RDS + +The following instructions show how to create a parameter group, enable logical replication, and add the parameter group to your AWS RDS PostgreSQL database. + +1. Create a parameter group for your RDS database (`RDS` > `Parameter groups` > `Create a parameter group`). In the **Parameter group family**, select your Postgres version. Select the type **DB Parameter group** option and assign a descriptive group name and description: + + ![Create a parameter group in AWS RDS](../images/aws-rds-create-parameter-group.png) + +2. Set the `rds.logical_replication` parameter to `1`(`true`) in the parameter group. + + ![Set logical replication parameter group](../images/set-logical-replication-parameter.png) + +3. Modify **Database options** (`RDS` > `Databases` > `Modify`) to use the new DB parameter group: + + ![Add Parameter group to AWS RDS](../images/add-group.png) + + To reflect the configuration change into `wal_level`, select the **Apply immediately** option. + +4. Go to `RDS` > `Databases` > `[database name]`, then click on **Actions**, and then click on **Reboot** to restart your database. diff --git a/content/400-pulse/250-database-setup/300-railway.mdx b/content/400-pulse/250-database-setup/300-railway.mdx new file mode 100644 index 0000000000..b09443c4b4 --- /dev/null +++ b/content/400-pulse/250-database-setup/300-railway.mdx @@ -0,0 +1,100 @@ +--- +title: 'Railway' +metaTitle: 'Prisma Pulse: Railway' +metaDescription: 'Instructions to use Railway with Prisma Pulse' +tocDepth: 3 +toc: true +--- + + + +[Railway.app](https://railway.app) offers an excellent [templates feature](https://railway.app/templates). If you wish to quickly start with Prisma Pulse, you can use either of two templates: + +- [Prisma Pulse DB Only](https://railway.app/template/pulse-pg): Provides a fresh, pre-configured PostgreSQL database which you can use with Prisma Pulse. +- [Prisma Pulse DB & App](https://railway.app/template/pulse-starter): Provides a pre-configured PostgreSQL database and a [Prisma Pulse starter app](https://github.com/prisma/pulse-starter). + + + +## Setup using the template + +
+ +1. Deploy the [template](https://railway.app/template/pulse-pg) on Railway + +2. Click on the service called `restart-db-then-delete-me`. + +3. You will see a list of deployments under the **Deployments** tab. + +4. Click the most recent build's **View Logs** button. + +5. Click on the **Deploy Logs** tab. + +> If the service ran correctly, you should see a message in the logs that says "All done please restart the database" along with your `DATABASE_URL` connection string. + +6. Copy the `DATABASE_URL` connection string and save it for later. Then restart your Railway database. + + - Click on your database. + + - Navigate to the Deployments tab. + + - Go into the three-dots menu on the latest deployment and click the `Restart` option. + +7. After restarting your database. Click on the `restart-db-then-delete-me` service and navigate to the **Settings** tab. + +8. Scroll down to the bottom and click the red **Delete Service** button. + + > Note: If you would like to use this service and the corresponding repository to create a new Prisma Pulse project. You can do so by cloning the repo from your GitHub account to your local machine. + + - Once you have cloned the repository, you can run the following command: + + ```bash + + bash rm config-db.ts + + ``` + + - Then remove the script `start: ts-node config-db.ts` from the `scripts` object in the `package.json` file. + + > This is to prevent the script from running every time you push up to the repo associated with the `restart-db-then-delete-me` service. + +## 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](https://docs.railway.app/databases/postgresql), or any other way you might run queries on your database. + + - Set the [wal_level](https://www.postgresql.org/docs/current/runtime-config-wal.html) to `logical`: + + ```sql + ALTER SYSTEM SET wal_level = logical; + ``` + + - Set the [max_replication_slots](https://www.postgresql.org/docs/current/runtime-config-replication.html) to `20`: + + ```sql + ALTER SYSTEM SET max_replication_slots = 20; + ``` + + - Set the [wal_keep_size](https://www.postgresql.org/docs/current/runtime-config-replication.html) to `2048`: + + ```sql + ALTER SYSTEM SET wal_keep_size = 2048; + ``` + + - Reload the PostgreSQL configuration: + + ```sql + SELECT pg_reload_conf(); + ``` + +2. Restart your database + + - Click on your database. + + - Navigate to the Deployments tab. + + - Go into the three-dots menu on the latest deployment and click the `Restart` option. + +After setting up your Railway database, you have to use the [connection string](https://docs.railway.app/guides/postgresql#tcp-proxy-connection) provided by Railway that allows public access your PostgreSQL database. diff --git a/content/400-pulse/250-database-setup/400-neon.mdx b/content/400-pulse/250-database-setup/400-neon.mdx new file mode 100644 index 0000000000..3539f8ee56 --- /dev/null +++ b/content/400-pulse/250-database-setup/400-neon.mdx @@ -0,0 +1,36 @@ +--- +title: 'Neon' +metaTitle: 'Prisma Pulse: Neon' +metaDescription: 'Instructions to use Neon for PostgreSQL with Prisma Pulse' +tocDepth: 3 +toc: true +--- + + + +To enable logical replication in Neon for Prisma Pulse, follow these steps: + + + +## Enable logical replication on Neon + +1. Enable logical replication in Neon console: + + - Navigate to your project in the Neon console. + - Access the **Project settings** from the Neon Dashboard. + - Go to the **Beta** section. + - Click on **Enable**. + + Learn more about enabling logical replication in Neon [here](https://neon.tech/docs/guides/logical-replication-neon#enabling-logical-replication-in-neon). + +2. Create publication for database events. Use the following SQL query to create a publication for all tables: + + ```sql + CREATE Publication $PUBLICATION_NAME FOR ALL TABLES; + ``` + + Additionally, you can manage specific models for which you want to listen to database events in Neon. Refer to [this](/pulse/database-setup/general-database-instructions#manage-your-own-publication-slot) section for more details on managing Publications. + +3. Before enabling Prisma Pulse, make sure to provide the publication name in the Platform Console: + + ![](../images/replication-slot-submission.png) diff --git a/content/400-pulse/250-database-setup/500-supabase.mdx b/content/400-pulse/250-database-setup/500-supabase.mdx new file mode 100644 index 0000000000..7d1a7b0fc6 --- /dev/null +++ b/content/400-pulse/250-database-setup/500-supabase.mdx @@ -0,0 +1,28 @@ +--- +title: 'Supabase' +metaTitle: 'Prisma Pulse: Supabase' +metaDescription: 'Instructions to use Supabase with Prisma Pulse' +tocDepth: 3 +toc: true +--- + + + +You have to use a direct database connection from Supabase to use it with Prisma Pulse. + + + +## Using a direct connection in Supabase + +To use a direct database connection string in Supabase: + +1. Navigate to your Project settings (`Settings` > `Configurations` > `Database`). +2. Disable the **Use connection pooling** option. + ![Supabase direct database connection](../images/supabase-direct-database-connection.png) +3. Copy the direct database connection string. + + + + ℹ️ Prisma Pulse is currently incompatible with Supabase's connection pooler. This results from the connection pooler intercepting the connection between your database and Prisma Pulse and removing the [Streaming Replication Protocol](https://www.postgresql.org/docs/current/protocol-replication.html#PROTOCOL-REPLICATION) which is used by Prisma Pulse to transmit replication commands to the database. + + diff --git a/content/400-pulse/250-database-setup/index.mdx b/content/400-pulse/250-database-setup/index.mdx new file mode 100644 index 0000000000..dfc023b474 --- /dev/null +++ b/content/400-pulse/250-database-setup/index.mdx @@ -0,0 +1,30 @@ +--- +title: 'Database setup' +metaTitle: 'Prisma Pulse: Database setup' +metaDescription: 'Learn about configuring your database to use with Prisma Pulse' +tocDepth: 3 +toc: true +--- + + + +Prepare your database to work with Prisma Pulse. + + + +## General database instruction + +Prisma Pulse requires your database to be configured in a specific way. To get your database ready for Prisma Pulse, follow the general database instructions [here](/pulse/database-setup/general-database-instructions). + + + +Prisma Pulse requires a publicly accessible PostgreSQL (**version 12+**) database with [logical replication](/pulse/database-setup/general-database-instructions#enable-logical-replication) enabled. + + + +## Provider specific instructions + +- [AWS RDS](/pulse/database-setup/aws-rds) +- [Railway](/pulse/database-setup/railway) +- [Supabase](/pulse/database-setup/supabase) +- [Neon](/pulse/database-setup/neon) diff --git a/content/400-pulse/300-concepts.mdx b/content/400-pulse/300-concepts.mdx index 022f04ee44..877ecdc28b 100644 --- a/content/400-pulse/300-concepts.mdx +++ b/content/400-pulse/300-concepts.mdx @@ -10,12 +10,26 @@ toc: true ## Change data capture -[Change data capture (CDC)](https://en.wikipedia.org/wiki/Change_data_capture) is a technique used to track and capture changes in a database enabling real-time updates. It allows applications to be informed about the modifications in the database, ensuring data consistency between multiple applications. +[Change data capture (CDC)](https://en.wikipedia.org/wiki/Change_data_capture) refers to the process of identifying and capturing changes made to data in a database and then delivering those changes in real-time to a downstream process or system. ## Logical replication Logical replication is a method of replicating data objects and their changes based on their replication identity (usually a primary key). You can read more about logical replication and how it pertains to your database in Postgres' documentation [here](https://www.postgresql.org/docs/current/logical-replication.html). +1. Create a logical replication slot: + + ```sql + SELECT pg_create_logical_replication_slot('$REPLICATION_SLOT_NAME', 'pgoutput'); + ``` + + Learn more [here](https://pgpedia.info/p/pg_create_logical_replication_slot.html). + +2. View your logical replication slots: + + ```sql + SELECT slot_name, slot_type FROM pg_replication_slots WHERE slot_type = 'logical'; + ``` + ## Write-ahead log A [write-ahead log (WAL)](https://www.postgresql.org/docs/current/wal-intro.html) is a standard way of ensuring data integrity by only allowing updates to the data in a database _after_ a log has been written to permanent storage describing the change to take place. diff --git a/content/400-pulse/400-api-reference.mdx b/content/400-pulse/400-api-reference.mdx index be10d8cfe6..f95660ca6e 100644 --- a/content/400-pulse/400-api-reference.mdx +++ b/content/400-pulse/400-api-reference.mdx @@ -1,6 +1,6 @@ --- -title: 'API Reference' -metaTitle: 'Pulse: API Reference' +title: 'API reference' +metaTitle: 'Pulse: API reference' metaDescription: 'API reference documentation for Pulse.' tocDepth: 4 toc: true diff --git a/content/400-pulse/500-current-limitations.mdx b/content/400-pulse/500-current-limitations.mdx deleted file mode 100644 index e625cf099e..0000000000 --- a/content/400-pulse/500-current-limitations.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: 'Current limitations' -metaTitle: 'Pulse: Current limitations' -metaDescription: 'Learn about current limitations of Pulse.' -tocDepth: 3 -toc: true ---- - - - -Below are descriptions of known limitations when using Pulse. If you are aware of any limitations that are missing, please let us know on the [#pulse-feedback](https://prisma.slack.com/archives/C058GKE3C1E) channel in our community Slack. - - - -## Superuser account required - -You must connect to your database instance from Pulse using a superuser account. In the future, we will enable non-superuser accounts with limited access privileges to be used with Pulse. - -## Limited throughput of change events - -While in Early Access, there may be limits to the throughput of change events that can be captured and delivered. We plan to provide transparent scale-up capabilities in the future. - -## Limited to 10 active subscriptions per table - -Initially you will be limited to 10 active subscriptions per table. This limitation will be lifted in the future. - -## Change events are not persisted - -Pulse does not persist change events and does not provide delivery guarantees with regards to ordering or exact-once/at-least-once delivery. - -An application must maintain an active connection to Pulse using the `subscribe()` method to capture change events; change events that occur while a Prisma Client is not subscribed will not be delivered. - -## Front-end use is not possible - -Pulse cannot be used in the front-end portion of an application. - - - -If you would find this capability valuable, please share your thoughts on the[#pulse-feedback](https://prisma.slack.com/archives/C058GKE3C1E) channel on our community Slack. - - - -## Limited to Postgres versions 12 or higher - -Pulse is currently supported with Postgres versions 12 or higher. It should work with most Postgres providers that expose Postgres’ native logical replication feature. We plan on adding support for MySQL in our GA release. - - - -If you have questions about whether your database is supported, please reach out to us on the [#pulse-feedback](https://prisma.slack.com/archives/C058GKE3C1E) channel on our community Slack. - - - -## Pulse will not attempt a reconnect or give an indication of the network is disconnected - -Currently, if there is some type of network disconnect while Prisma Client is subscribed to Pulse, there will be no attempts to reconnect or indicate the connection has dropped. - -For example, if you are evaluating Pulse from an application running on your laptop and it goes to sleep resulting in a network disruption, it can appear as though the Prisma Client instance is still subscribed to Pulse when it is not. - -We will soon add heart-beating capability that throws an error to the Prisma Client when the connection is no longer active so the application can reconnect. - -## Self-signed certificates are not supported yet - -Prisma Pulse is not compatible with self-signed certificates yet. Cloud providers using these certificates will only work if the [`sslmode`](/orm/overview/databases/postgresql#configuring-an-ssl-connection) is set to `sslmode=disable`. Pulse works with any certificate provided the `sslmode` is set to `disable`. _This is a Prisma Pulse [Early Access](/platform/maturity-levels#early-access) limitation that will be lifted before Prisma Pulse [General Availability](/platform/maturity-levels#general-availability)_. diff --git a/content/400-pulse/500-known-limitations.mdx b/content/400-pulse/500-known-limitations.mdx new file mode 100644 index 0000000000..1abf12a466 --- /dev/null +++ b/content/400-pulse/500-known-limitations.mdx @@ -0,0 +1,36 @@ +--- +title: 'Known limitations' +metaTitle: 'Pulse: Known limitations' +metaDescription: 'Learn about known limitations of Pulse.' +tocDepth: 3 +toc: true +--- + + + +Below are descriptions of known limitations when using Prisma Pulse. If you are aware of any limitations that are missing, please let us know on the `#help-and-questions` channel in our community [Discord](https://pris.ly/discord). + + + +## Superuser role required for starter plan + +Our [Starter plan](https://www.prisma.io/pricing) requires a database role with superuser access. + +## Database events are not persisted + +Prisma Pulse does not persist database events and does not provide delivery guarantees regarding ordering or exact-once/at-least-once delivery. + +To capture database events, an application must maintain an active connection to Pulse using the  [`subscribe()`](/pulse/api-reference#subscribe) method. + +It's important to note scenarios where database events may not be delivered: + +1. **Inactive subscriptions**: If no active subscriptions match the filters of the database event. +2. **Exceeding database event size limits**: Database events surpassing predefined size limits. + +## Prisma Pulse is server-side + +Prisma Pulse subscriptions cannot be initiated directly within client-side code. + +## Limited to Postgres versions 12 or higher + +Prisma Pulse is currently supported with Postgres versions 12 or higher. It should work with most Postgres providers that expose Postgres’ native logical replication feature. diff --git a/content/400-pulse/600-faq.mdx b/content/400-pulse/600-faq.mdx index e5c1ab1e46..ecd529e12e 100644 --- a/content/400-pulse/600-faq.mdx +++ b/content/400-pulse/600-faq.mdx @@ -1,48 +1,60 @@ --- title: 'FAQ' -metaTitle: 'Pulse: FAQ' -metaDescription: 'Frequently asked questions about Pulse.' +metaTitle: 'Prisma Pulse: FAQ' +metaDescription: 'Frequently asked questions about Prisma Pulse.' tocDepth: 3 toc: true --- -Below are frequently asked questions about Pulse. + -## Does Pulse work in a serverless environment? +Below are frequently asked questions about Prisma Pulse. -Pulse will natively support serverless environments soon after it launches to [General Availability](/platform/maturity-levels#general-availability). + -While in [Early Access](/platform/maturity-levels#early-access), Pulse works best when it is able to maintain a long-running active connection with your application. However, many serverless runtime providers limit the duration of serverless functions. We’re actively working on improving the experience in serverless applications. +## What databases are supported with Prisma Pulse? + +Currently, Pulse supports PostgreSQL. We plan to broaden support to include more databases soon. -Please reach out to us on the [#pulse-feedback](https://prisma.slack.com/archives/C058GKE3C1E) channel on our community Slack if having a more native serverless approach to getting data change events is important to you. +Note: Pulse compatibility with Postgres-like databases depends on their logical replication capabilities. -## How does Pulse handle schema changes in the database? + -Pulse is designed to work seamlessly with schema changes in your database by utilizing [Change data capture (CDC)](https://en.wikipedia.org/wiki/Change_data_capture) techniques and combining that with the power of schema-driven data access using [Prisma Client](/orm/prisma-client). When your Prisma schema is updated, Pulse automatically adapts to the changes, ensuring that your real-time data synchronization remains consistent and reliable. +Prisma Pulse’s database compatibility list will be different from Prisma Client's database compatibility list. If you want to use Prisma Pulse with an existing application using Prisma ORM, please verify the database and hosting provider are supported. -Pulse leverages the type information generated by Prisma to create type-safe database subscriptions, allowing you to catch potential issues at compile time and maintain the integrity of your data throughout the development process. This approach allows Pulse to efficiently capture and propagate data changes while maintaining compatibility with evolving database structures. + -## What databases are supported with Pulse? +### What database providers are supported with Prisma Pulse? -The Pulse Early Access release supports PostgreSQL with plans to extend support to MySQL in the near future. +| Provider | Starter | Pro | Business | Enterprise | +| -------- | ------- | --- | -------- | ---------- | +| Railway | ✅ | ✅ | ✅ | ✅ | +| Supabase | ✅ | ✅ | ✅ | ✅ | +| Neon | ❌ | ✅ | ✅ | ✅ | +| AWS RDS | ✅ | ✅ | ✅ | ✅ | -Pulse primarily interfaces with a database's write-ahead log (Postgres) or binlog (MySQL) to efficiently capture data change events, offering a more performant solution than regular polling through scheduled queries. Note that Pulse may not work with every Postgres-compatible database, as compatibility depends on the exposure of Postgres-native logical replication capabilities required for change data capture. +## Does Pulse store my database events? - +Pulse does not persist database events and does not provide delivery guarantees regarding ordering or exact-once/at-least-once delivery. +To capture database events, an application must maintain an active connection to Pulse using the subscribe method. Any events occurring without an active subscription will be discarded. -Pulse’s database compatibility list will be different from Prisma Client's database compatibility list. If you want to use Pulse with an existing Prisma application, please verify the database and hosting provider are supported by Pulse. +## How can I increase the throughput for Prisma Pulse? - +Throughput for Prisma Pulse will increase as the Database event size decreases and the number of concurrent listeners decreases. + +While ensuring Database event size can be tricky, we recommend some best practices, such as: + +- Avoid large fields in your model, such as storing base64 image strings in the database; Instead, consider storing them in popular file storage options such as AWS S3 or Cloudflare. + +- Creating publication slots for specific models rather than all the models in the database. You can learn more about managing your replication slots [here](/pulse/getting-started#configuring-replication-slots). + +- Upgrading to use modern versions of PostgreSQL due to performance optimizations. + > ℹ️ Modern versions of PostgreSQL (`v15`+) allow you to create a publication slot for specific fields of a particular model. -## What database providers are supported with Pulse? +## Can I use Pulse in my front-end code? -| Provider | Support | Notes | -| -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Railway | ✅ | Requires [`sslmode=disable`](/orm/overview/databases/postgresql#configuring-an-ssl-connection) due to the use of a self-signed certificate for database connections by Railway. | -| Supabase | ✅ | Requires [`sslmode=disable`](/orm/overview/databases/postgresql#configuring-an-ssl-connection) due to the use of a self-signed certificate for database connections by Supabase. | -| Neon | _Coming_ | Support details coming soon. | -| AWS RDS | _Coming_ | Support details coming soon. | +No, Pulse is server-side and subscriptions cannot be initiated directly within client-side code. If you would find this feature valuable, please share your thoughts on the `#help-and-questions` channel in our community [Discord](https://pris.ly/discord). diff --git a/content/400-pulse/700-feedback.mdx b/content/400-pulse/700-feedback.mdx index defdda8d95..8fe9bf14bf 100644 --- a/content/400-pulse/700-feedback.mdx +++ b/content/400-pulse/700-feedback.mdx @@ -1,13 +1,13 @@ --- title: 'Feedback' -metaTitle: 'Pulse: Feedback' -metaDescription: 'Learn where to submit feedback about Pulse.' +metaTitle: 'Prisma Pulse: Feedback' +metaDescription: 'Learn where to submit feedback about Prisma Pulse.' tocDepth: 3 toc: true --- -You can submit any feedback about Pulse in the [#pulse-feedback](https://prisma.slack.com/archives/C058GKE3C1E) channel in our community Slack. +You can submit any feedback about Prisma Pulse in the `#help-and-questions` channel in our community [Discord](https://pris.ly/discord). diff --git a/content/400-pulse/images/add-group.png b/content/400-pulse/images/add-group.png new file mode 100644 index 0000000000..083ac2897d Binary files /dev/null and b/content/400-pulse/images/add-group.png differ diff --git a/content/400-pulse/images/aws-rds-create-parameter-group.png b/content/400-pulse/images/aws-rds-create-parameter-group.png new file mode 100644 index 0000000000..20e969cb77 Binary files /dev/null and b/content/400-pulse/images/aws-rds-create-parameter-group.png differ diff --git a/content/400-pulse/images/pulse-usecase.png b/content/400-pulse/images/pulse-usecase.png new file mode 100644 index 0000000000..2bc05b4742 Binary files /dev/null and b/content/400-pulse/images/pulse-usecase.png differ diff --git a/content/400-pulse/images/replication-slot-submission.png b/content/400-pulse/images/replication-slot-submission.png new file mode 100644 index 0000000000..7815f39f95 Binary files /dev/null and b/content/400-pulse/images/replication-slot-submission.png differ diff --git a/content/400-pulse/images/set-logical-replication-parameter.png b/content/400-pulse/images/set-logical-replication-parameter.png new file mode 100644 index 0000000000..451aa42ab0 Binary files /dev/null and b/content/400-pulse/images/set-logical-replication-parameter.png differ diff --git a/content/400-pulse/images/supabase-direct-database-connection.png b/content/400-pulse/images/supabase-direct-database-connection.png new file mode 100644 index 0000000000..c7cbf59ab2 Binary files /dev/null and b/content/400-pulse/images/supabase-direct-database-connection.png differ diff --git a/content/400-pulse/index.mdx b/content/400-pulse/index.mdx index c8072bcb67..6647275405 100644 --- a/content/400-pulse/index.mdx +++ b/content/400-pulse/index.mdx @@ -3,7 +3,6 @@ title: 'Pulse' metaTitle: 'Prisma Pulse' metaDescription: 'Prisma Pulse enables real-time database events with type-safe Prisma Client subscriptions.' toc: false -earlyaccess: true --- diff --git a/vercel.json b/vercel.json index 73b16a8d85..bebbe5c5ec 100644 --- a/vercel.json +++ b/vercel.json @@ -475,502 +475,402 @@ "source": "/docs/guides/prisma-guides/prisma-migrate-guides", "destination": "/docs/guides/prisma-guides/add-prisma-migrate-to-a-project" }, - { "source": "/docs/guides/prisma-guides/prisma-migrate-guides/add-prisma-migrate-to-a-project", "destination": "/docs/guides/prisma-guides/add-prisma-migrate-to-a-project" }, - { "source": "/docs/concepts/components/prisma-client/distinct", "destination": "/docs/concepts/components/prisma-client/aggregation-grouping-summarizing#select-distinct" }, - { "source": "/docs/concepts/components/prisma-client/configuring-the-prisma-client-api", "destination": "/docs/concepts/components/prisma-client/generating-prisma-client/customizing-the-prisma-client-api" }, - { "source": "/docs/concepts/components/prisma-client/constructor", "destination": "/docs/reference/api-reference/prisma-client-reference#prismaclient" }, - { "source": "/docs/concepts/components/prisma-client/field-selection", "destination": "/docs/concepts/components/prisma-client/select-fields" }, - { "source": "/docs/concepts/components/prisma-client/error-reference", "destination": "/docs/reference/api-reference/error-reference" }, - { "source": "/docs/concepts/components/prisma-client/sorting", "destination": "/docs/concepts/components/prisma-client/filtering-and-sorting" }, - { "source": "/docs/concepts/components/prisma-client/filtering", "destination": "/docs/concepts/components/prisma-client/filtering-and-sorting" }, - { "source": "/docs/concepts/components/prisma-client/aggregations", "destination": "/docs/concepts/components/prisma-client/aggregation-grouping-summarizing" }, - { "source": "/docs/concepts/components/prisma-client/working-with-json", "destination": "/docs/concepts/components/prisma-client/working-with-advanced-types" }, - { "source": "/docs/concepts/components/prisma-client/group-by", "destination": "/docs/concepts/components/prisma-client/aggregation-grouping-summarizing#group-by-preview" }, - { "source": "/docs/concepts/components/prisma-client/advanced-usage-of-generated-types", "destination": "/docs/concepts/components/prisma-client/working-with-generated-types" }, - { "source": "/docs/concepts/components/preview-features/native-types/native-types-mappings", "destination": "/docs/reference/api-reference/prisma-schema-reference#model-field-scalar-types" }, - { "source": "/docs/concepts/components/preview-features/native-types", "destination": "/docs/concepts/components/prisma-schema/data-model#native-types-mapping" }, - { "source": "/docs/concepts/components/prisma-client/generating-prisma-client", "destination": "/docs/concepts/components/prisma-client/working-with-prismaclient/generating-prisma-client" }, - { "source": "/docs/concepts/components/prisma-client/generating-prisma-client/customizing-the-prisma-client-api", "destination": "/docs/concepts/components/prisma-client/working-with-prismaclient/use-custom-model-and-field-names" }, - { "source": "/docs/concepts/components/prisma-client/connection-management", "destination": "/docs/concepts/components/prisma-client/working-with-prismaclient/connection-management" }, - { "source": "/docs/concepts/components/prisma-client/logging", "destination": "/docs/concepts/components/prisma-client/working-with-prismaclient/logging" }, - { "source": "/docs/concepts/components/prisma-client/error-formatting", "destination": "/docs/concepts/components/prisma-client/working-with-prismaclient/error-formatting" }, - { "source": "/docs/concepts/components/prisma-client/deployment", "destination": "/docs/guides/deployment/deployment" }, - { "source": "/docs/concepts/components/prisma-migrate/prisma-migrate-flows", "destination": "/docs/concepts/components/prisma-migrate" }, - { "source": "/docs/guides/prisma-guides/seed-database", "destination": "/docs/guides/application-lifecycle/seed-database" }, - { "source": "/docs/guides/prisma-guides/add-prisma-migrate-to-a-project", "destination": "/docs/guides/database/developing-with-prisma-migrate/add-prisma-migrate-to-a-project" }, - { "source": "/docs/about/creating-bug-reports", "destination": "/docs/support/creating-bug-reports" }, - { "source": "/docs/concepts/components/prisma-client/working-with-generated-types", "destination": "/docs/concepts/components/prisma-client/advanced-type-safety/operating-against-partial-structures-of-model-types" }, - { "source": "/docs/reference/utility-types-reference", "destination": "/docs/reference/api-reference/prisma-client-reference#prismavalidator" }, - { "source": "/docs/concepts/components/prisma-client/query-engine", "destination": "/docs/concepts/components/prisma-engines/query-engine" }, - { "source": "/docs/concepts/overview/under-the-hood", "destination": "/docs/concepts/components/prisma-engines" }, - { "source": "/docs/guides/application-lifecycle/add-prisma-migrate-to-a-project", "destination": "/docs/guides/database/developing-with-prisma-migrate/add-prisma-migrate-to-a-project" }, - { "source": "/docs/guides/deployment/patching-production", "destination": "/docs/guides/database/patching-production" }, - { "source": "/docs/guides/deployment/production-troubleshooting", "destination": "/docs/guides/database/production-troubleshooting" }, - { "source": "/docs/guides/application-lifecycle/:any*", "destination": "/docs/guides/database/:any*" }, - { "source": "/docs/guides/deployment/deploying-to-azure-functions", "destination": "/docs/guides/deployment/deployment-guides/deploying-to-azure-functions" }, - { "source": "/docs/guides/deployment/deploying-to-heroku", "destination": "/docs/guides/deployment/deployment-guides/deploying-to-heroku" }, - { "source": "/docs/guides/deployment/deploying-to-vercel", "destination": "/docs/guides/deployment/deployment-guides/deploying-to-vercel" }, - { "source": "/docs/guides/deployment/deploying-to-aws-lambda", "destination": "/docs/guides/deployment/deployment-guides/deploying-to-aws-lambda" }, - { "source": "/docs/guides/deployment/deploying-to-netlify", "destination": "/docs/guides/deployment/deployment-guides/deploying-to-netlify" }, - { "source": "/docs/guides/general-guides/database-workflows/cascading-deletes/:any*", "destination": "/docs/concepts/components/prisma-schema/relations/referential-actions" }, - { "source": "/docs/guides/database/advanced-database-tasks/cascading-deletes/:any*", "destination": "/docs/concepts/components/prisma-schema/relations/referential-actions" }, - { "source": "/docs/guides/general-guides/database-workflows/data-validation/:any*", "destination": "/docs/guides/database/advanced-database-tasks/data-validation/:any*" }, - { "source": "/docs/guides/general-guides/database-workflows/sql-views", "destination": "https://github.com/prisma/prisma/issues/678" }, - { "source": "/docs/guides/general-guides/database-workflows/sql-views-postgres", "destination": "https://github.com/prisma/prisma/issues/678" }, - { "source": "/docs/guides/database/advanced-database-tasks/sql-views-postgres", "destination": "https://github.com/prisma/prisma/issues/678" }, - { "source": "/docs/guides/general-guides/database-workflows/sql-views-mysql", "destination": "https://github.com/prisma/prisma/issues/678" }, - { "source": "/docs/guides/database/advanced-database-tasks/sql-views-mysql", "destination": "https://github.com/prisma/prisma/issues/678" }, - { "source": "/docs/guides/general-guides/database-workflows/unique-constraints-and-indexes", "destination": "/docs/concepts/components/prisma-schema/data-model#defining-a-unique-field" }, - { "source": "/docs/guides/general-guides/database-workflows/unique-constraints-and-indexes/mysql", "destination": "/docs/concepts/components/prisma-schema/data-model#defining-a-unique-field" }, - { "source": "/docs/guides/database/advanced-database-tasks/unique-constraints-and-indexes/postgresql", "destination": "/docs/concepts/components/prisma-schema/data-model#defining-a-unique-field" }, - { "source": "/docs/guides/general-guides/database-workflows/unique-constraints-and-indexes/sqlite", "destination": "/docs/concepts/components/prisma-schema/data-model#defining-a-unique-field" }, - { "source": "/docs/guides/general-guides/database-workflows/foreign-keys", "destination": "/docs/concepts/components/prisma-schema/relations#relational-databases" }, - { "source": "/docs/guides/general-guides/database-workflows/foreign-keys/mysql", "destination": "/docs/concepts/components/prisma-schema/relations#relational-databases" }, - { "source": "/docs/guides/general-guides/database-workflows/foreign-keys/postgresql", "destination": "/docs/concepts/components/prisma-schema/relations#relational-databases" }, - { "source": "/docs/guides/general-guides/database-workflows/foreign-keys/sqlite", "destination": "/docs/concepts/components/prisma-schema/relations#relational-databases" }, - { "source": "/docs/guides/prisma-guides/:any*", "destination": "/docs/guides/performance-and-optimization/:any*" }, - { "source": "/docs/mongodb", "destination": "/docs/concepts/database-connectors/mongodb" }, - { "source": "/docs/guides/database/developing-with-prisma-migrate/advanced-migrate-scenarios", "destination": "/docs/guides/database/developing-with-prisma-migrate/customizing-migrations" }, - { "source": "/docs/concepts/components/prisma-migrate/type-mapping", "destination": "/docs/concepts/components/prisma-migrate/supported-types-and-db-features" }, - { "source": "/docs/concepts/components/prisma-client/working-with-advanced-types", "destination": "/docs/concepts/components/prisma-client/working-with-fields" }, - { "source": "/docs/concepts/more/codemod", "destination": "/docs/guides/upgrade-guides/upgrading-versions/codemods" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch-typescript-postgres", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases-typescript-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project-typescript-postgres", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases-typescript-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/connect-your-database-typescript-postgres", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/connect-your-database-typescript-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/using-prisma-migrate-typescript-postgres", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/using-prisma-migrate-typescript-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/install-prisma-client-typescript-postgres", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/install-prisma-client-typescript-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/querying-the-database-typescript-postgres", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/querying-the-database-typescript-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/next-steps-typescript-postgres", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/next-steps-typescript-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/connect-your-database-typescript-postgres", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/connect-your-database-typescript-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/introspection-typescript-postgres", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/introspection-typescript-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/install-prisma-client-typescript-postgres", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/install-prisma-client-typescript-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/querying-the-database-typescript-postgres", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/querying-the-database-typescript-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/next-steps-typescript-postgres", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/next-steps-typescript-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/connect-your-database-node-postgres", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/connect-your-database-node-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/using-prisma-migrate-node-postgres", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/using-prisma-migrate-node-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/install-prisma-client-node-postgres", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/install-prisma-client-node-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/querying-the-database-node-postgres", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/querying-the-database-node-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/next-steps-node-postgres", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/next-steps-node-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/connect-your-database-node-postgres", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/connect-your-database-node-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/introspection-node-postgres", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/introspection-node-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/install-prisma-client-node-postgres", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/install-prisma-client-node-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/querying-the-database-node-postgres", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/querying-the-database-node-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/next-steps-node-postgres", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/next-steps-node-postgresql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/connect-your-database-typescript-mysql", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/connect-your-database-typescript-mysql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/using-prisma-migrate-typescript-mysql", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/using-prisma-migrate-typescript-mysql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/install-prisma-client-typescript-mysql", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/install-prisma-client-typescript-mysql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/querying-the-database-typescript-mysql", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/querying-the-database-typescript-mysql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/next-steps-typescript-mysql", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/next-steps-typescript-mysql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/connect-your-database-typescript-mysql", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/connect-your-database-typescript-mysql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/introspection-typescript-mysql", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/introspection-typescript-mysql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/install-prisma-client-typescript-mysql", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/install-prisma-client-typescript-mysql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/querying-the-database-typescript-mysql", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/querying-the-database-typescript-mysql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/next-steps-typescript-mysql", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/next-steps-typescript-mysql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/connect-your-database-node-mysql", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/connect-your-database-node-mysql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/using-prisma-migrate-node-mysql", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/using-prisma-migrate-node-mysql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/install-prisma-client-node-mysql", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/install-prisma-client-node-mysql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/querying-the-database-node-mysql", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/querying-the-database-node-mysql" }, - { "source": "/docs/getting-started/setup-prisma/start-from-scratch/next-steps-node-mysql", "destination": "/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/next-steps-node-mysql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/connect-your-database-node-mysql", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/connect-your-database-node-mysql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/introspection-node-mysql", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/introspection-node-mysql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/install-prisma-client-node-mysql", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/install-prisma-client-node-mysql" }, - { "source": "/docs/getting-started/setup-prisma/add-to-existing-project/querying-the-database-node-mysql", "destination": "/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/querying-the-database-node-mysql" @@ -3886,6 +3786,26 @@ { "source": "/docs/orm/prisma-client/deployment/module-bundlers", "destination": "/docs/orm/prisma-client/deployment/module-bundlers" + }, + { + "source": "/docs/pulse/current-limitations", + "destination": "/docs/pulse/known-limitations", + "statusCode": 301 + }, + { + "source": "/docs/pulse/current-limitations#change-events-are-not-persisted", + "destination": "/docs/pulse/known-limitations#database-events-are-not-persisted", + "statusCode": 301 + }, + { + "source": "/pulse/current-limitations", + "destination": "/pulse/known-limitations", + "statusCode": 301 + }, + { + "source": "/pulse/getting-started#configuring-replication-slot", + "destination": "/pulse/database-setup/general-database-instructions#enable-logical-replication", + "statusCode": 301 } ] }