From ebd079050bf7fce9a5d009896d71524a751969f4 Mon Sep 17 00:00:00 2001 From: Luan van der Westhuizen <6928171+luanvdw@users.noreply.github.com> Date: Tue, 19 Mar 2024 12:32:56 +0200 Subject: [PATCH 1/8] fix: edge deployment targets (#5733) --- content/300-accelerate/200-getting-started.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/300-accelerate/200-getting-started.mdx b/content/300-accelerate/200-getting-started.mdx index e4825be050..70e096d373 100644 --- a/content/300-accelerate/200-getting-started.mdx +++ b/content/300-accelerate/200-getting-started.mdx @@ -134,7 +134,7 @@ import { withAccelerate } from '@prisma/extension-accelerate' const prisma = new PrismaClient().$extends(withAccelerate()) ``` -If you are going to deploy to an edge runtime (like Cloudflare Workers, Vercel Edge Functions, Deno Deploy, or Netlify Edge Functions), use our edge client instead: +If you are going to deploy to an edge runtime (like Cloudflare Workers, Vercel Edge Functions, Deno Deploy, or Supabase Edge Functions), use our edge client instead: ```ts import { PrismaClient } from '@prisma/client/edge' From aa684373751943d2422676befc3ac39ca00637a6 Mon Sep 17 00:00:00 2001 From: Luan van der Westhuizen <6928171+luanvdw@users.noreply.github.com> Date: Wed, 20 Mar 2024 16:20:43 +0200 Subject: [PATCH 2/8] feat: Pulse expansion survey (#5736) * feat: added survey * 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 | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/content/400-pulse/200-getting-started.mdx b/content/400-pulse/200-getting-started.mdx index 390362a901..1f60b3d916 100644 --- a/content/400-pulse/200-getting-started.mdx +++ b/content/400-pulse/200-getting-started.mdx @@ -10,6 +10,12 @@ toc: true ## Prerequisites + + +💡 Prisma Pulse currently supports PostgreSQL. We'd love to hear [which databases](https://tally.so/r/wLbb8G) you would like to see supported next. + + + You'll need the following to integrate Prisma Pulse into your application; - Prisma Data Platform workspace From 973bf5b0e4521e3025bc6f6ed9666ebedd6cd163 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Wed, 20 Mar 2024 21:55:51 +0600 Subject: [PATCH 3/8] docs: add limitation on pulse type generation (#5737) --- content/400-pulse/500-known-limitations.mdx | 26 +++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/content/400-pulse/500-known-limitations.mdx b/content/400-pulse/500-known-limitations.mdx index 1abf12a466..d892ef8f42 100644 --- a/content/400-pulse/500-known-limitations.mdx +++ b/content/400-pulse/500-known-limitations.mdx @@ -34,3 +34,29 @@ 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. + +## Subscription type limitation with custom publication slots + +Our advanced onboarding flow enables you to provide a [custom publication slot](/pulse/database-setup/general-database-instructions#manage-your-own-publication-slot). Should that custom publication slot only contains a subset of your database tables, the Prisma Client generated with the Pulse Client Extension will continue to permit subscriptions to all models based on the entirety of your Prisma Schema definitions. + +For example, if you have two models in your schema, the `User` and `Post` model. And you opt to create a publication to monitor changes in the `User` model exclusively: + +```sql +CREATE PUBLICATION user_publication FOR TABLE users; +``` + +> To learn more about creating custom publication slots, see [managing your publication slot](https://www.prisma.io/docs/pulse/database-setup/general-database-instructions#manage-your-own-publication-slot). + +Your resulting subscription code would be: + +```ts +const userSubscription = prisma.user.subscribe() +``` + +However, despite the absence of publication coverage, the generated Prisma client permits subscriptions for all models, such as the `Post` model: + +```ts +const postSubscription = prisma.post.subscribe() +``` + +> We are actively working on enhancing type generation for custom publications as part of our ongoing efforts to further refine Prisma Pulse. 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 4/8] 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. From 0211b13e15171d2e81b613426ac24496ecb4609e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Otto=20Kek=C3=A4l=C3=A4inen?= Date: Thu, 21 Mar 2024 06:28:31 -0700 Subject: [PATCH 5/8] MariaDB mentions (#5713) * Show MariaDB logo in list of databases For new users learning about Prisma it is unclear if Prisma properly supports MariaDB or not. Mentioning MariaDB explicitly makes it easy for users to find that Prisma does indeed support MariaDB. * Mention MariaDB alongside MySQL in the basic tutorials When reading the Getting Started tutorial, FAQ and similar introductory pages it is unclear if Prisma properly supports MariaDB or not. Mentioning MariaDB explicitly makes it easy for users to find that Prisma does indeed support MariaDB. * Extend MySQL page to also cover MariaDB use --------- Co-authored-by: Jon Harrell <4829245+jharrell@users.noreply.github.com> --- .../050-overview/500-databases/400-mysql.mdx | 43 ++++++++++++++++--- .../410-referential-actions/index.mdx | 20 ++++----- .../200-shadow-database.mdx | 2 +- .../500-reference/375-supported-databases.mdx | 5 ++- .../300-accelerate/200-getting-started.mdx | 2 +- src/components/shortcodes/index.tsx | 2 + 6 files changed, 53 insertions(+), 21 deletions(-) diff --git a/content/200-orm/050-overview/500-databases/400-mysql.mdx b/content/200-orm/050-overview/500-databases/400-mysql.mdx index 580e0e727a..226ec93f6c 100644 --- a/content/200-orm/050-overview/500-databases/400-mysql.mdx +++ b/content/200-orm/050-overview/500-databases/400-mysql.mdx @@ -1,13 +1,13 @@ --- -title: 'MySQL' +title: 'MySQL/MariaDB' metaTitle: 'MySQL database connector' -metaDescription: 'This page explains how Prisma can connect to a MySQL database using the MySQL database connector.' +metaDescription: 'This page explains how Prisma can connect to a MySQL or MariaDB database using the MySQL database connector.' tocDepth: 3 --- -The MySQL data source connector connects Prisma ORM to a [MySQL](https://www.mysql.com/) database server. +The MySQL data source connector connects Prisma ORM to a [MySQL](https://www.mysql.com/) or [MariaDB](https://mariadb.org/) database server. By default, the MySQL connector contains a database driver responsible for connecting to your database. You can use a [driver adapter](/orm/overview/databases/database-drivers#driver-adapters) (Preview) to connect to your database using a JavaScript database driver from Prisma Client. @@ -26,7 +26,7 @@ datasource db { The fields passed to the `datasource` block are: -- `provider`: Specifies the `mysql` data source connector. +- `provider`: Specifies the `mysql` data source connector, which is used both for MySQL and MariaDB. - `url`: Specifies the [connection URL](#connection-url) for the MySQL database server. In this case, an [environment variable is used](/orm/prisma-schema/overview#accessing-environment-variables-from-the-schema) to provide the connection URL. ## Connection details @@ -50,7 +50,7 @@ The following components make up the _base URL_ of your database, they are alway | Name | Placeholder | Description | | :------- | :---------- | :------------------------------------------------------------------------------------------------------------------ | | Host | `HOST` | IP address/domain of your database server, e.g. `localhost` | -| Port | `PORT` | Port on which your database server is running, e.g. `5432` | +| Port | `PORT` | Port on which your database server is running, e.g. `5432` (default is `3306`, or no port when using Unix socket) | | User | `USER` | Name of your database user, e.g. `janedoe` | | Password | `PASSWORD` | Password for your database user | | Database | `DATABASE` | Name of the [database](https://dev.mysql.com/doc/refman/8.0/en/creating-database.html) you want to use, e.g. `mydb` | @@ -112,8 +112,8 @@ mysql://USER:PASSWORD@HOST:PORT/DATABASE?sslidentity=client-identity.p12&sslpass ### Connecting via sockets -To connect to your MySQL database via sockets, you must add a `socket` field as a _query parameter_ to the connection URL (instead of setting it as the `host` part of the URI). -The value of this parameter then must point to the directory that contains the socket, e.g.: `mysql://USER:POST@localhost/database?socket=/var/run/mysql/` +To connect to your MySQL/MariaDB database via a socket, you must add a `socket` field as a _query parameter_ to the connection URL (instead of setting it as the `host` part of the URI). +The value of this parameter then must point to the directory that contains the socket, e.g. on a default installation of MySQL/MariaDB on Ubuntu or Debian use: `mysql://USER:POST@localhost/database?socket=/run/mysqld/mysqld.sock` Note that `localhost` is required, the value itself is ignored and can be anything. @@ -139,6 +139,20 @@ The MySQL connector maps the [scalar types](/orm/prisma-schema/data-model/models | `Json` | `JSON` | Supported in MySQL 5.7+ only | | `Bytes` | `LONGBLOB` | +### Native type mapping from Prisma ORM to MariaDB + +| Prisma ORM | MariaDB | Notes | +| ---------- | ---------------- | -------------------------------------------------- | +| `String` | `VARCHAR(191)` | | +| `Boolean` | `BOOLEAN` | In MariaDB `BOOLEAN` is a synonym for `TINYINT(1)` | +| `Int` | `INT` | | +| `BigInt` | `BIGINT` | | +| `Float` | `DOUBLE` | | +| `Decimal` | `DECIMAL(65,30)` | | +| `DateTime` | `DATETIME(3)` | | +| `Json` | `LONGTEXT | See https://mariadb.com/kb/en/json-data-type/ | +| `Bytes` | `LONGBLOB` | | + ### Native type mappings When introspecting a MySQL database, the database types are mapped to Prisma ORM according to the following table: @@ -204,3 +218,18 @@ model Device { ## Engine If you are using a version of MySQL where MyISAM is the default engine, you must specify `ENGINE = InnoDB;` when you create a table. If you introspect a database that uses a different engine, relations in the Prisma Schema are not created (or lost, if the relation already existed). + +## Permissions + +A fresh new installation of MySQL/MariaDB has by default only a `root` database user. Do not use `root` user in your Prisma configuration, but instead create a database and database user for each application. On most Linux hosts (e.g. Ubuntu) you can simply run this as the Linux `root` user (which automatically has database `root` access as well): + +``` +mysql -e "CREATE DATABASE IF NOT EXISTS $DB_PRISMA;" +mysql -e "GRANT ALL PRIVILEGES ON $DB_PRISMA.* TO $DB_USER@'%' IDENTIFIED BY '$DB_PASSWORD';" +``` + +The above is enough to run the `prisma db pull` and `prisma db push` commands. In order to also run `prisma migrate` commands these permissions need to be granted: + +``` +mysql -e "GRANT CREATE, DROP, REFERENCES, ALTER ON *.* TO $DB_USER@'%';" +``` diff --git a/content/200-orm/100-prisma-schema/20-data-model/20-relations/410-referential-actions/index.mdx b/content/200-orm/100-prisma-schema/20-data-model/20-relations/410-referential-actions/index.mdx index 43a00f61fe..c895a0e668 100644 --- a/content/200-orm/100-prisma-schema/20-data-model/20-relations/410-referential-actions/index.mdx +++ b/content/200-orm/100-prisma-schema/20-data-model/20-relations/410-referential-actions/index.mdx @@ -150,14 +150,14 @@ The following caveats apply: The following table shows which referential action each database supports. -| Database | Cascade | Restrict | NoAction | SetNull | SetDefault | -| :---------- | :------ | :------- | :------- | :------ | :--------- | -| PostgreSQL | ✔️ | ✔️ | ✔️ | ✔️⌘ | ✔️ | -| MySQL | ✔️ | ✔️ | ✔️ | ✔️ | ❌ (✔️†) | -| SQLite | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | -| SQL Server | ✔️ | ❌‡ | ✔️ | ✔️ | ✔️ | -| CockroachDB | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | -| MongoDB†† | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | +| Database | Cascade | Restrict | NoAction | SetNull | SetDefault | +| :------------ | :------ | :------- | :------- | :------ | :--------- | +| PostgreSQL | ✔️ | ✔️ | ✔️ | ✔️⌘ | ✔️ | +| MySQL/MariaDB | ✔️ | ✔️ | ✔️ | ✔️ | ❌ (✔️†) | +| SQLite | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| SQL Server | ✔️ | ❌‡ | ✔️ | ✔️ | ✔️ | +| CockroachDB | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| MongoDB†† | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | - † See [special cases for MySQL](#mysql). - ⌘ See [special cases for PostgreSQL](#postgresql). @@ -168,9 +168,9 @@ The following table shows which referential action each database supports. Referential actions are part of the ANSI SQL standard. However, there are special cases where some relational databases diverge from the standard. -#### MySQL +#### MySQL/MariaDB -MySQL, and the underlying InnoDB storage engine, does not support `SetDefault`. The exact behavior depends on the database version: +MySQL/MariaDB, and the underlying InnoDB storage engine, does not support `SetDefault`. The exact behavior depends on the database version: - In MySQL versions 8 and later, and MariaDB versions 10.5 and later, `SetDefault` effectively acts as an alias for `NoAction`. You can define tables using the `SET DEFAULT` referential action, but a foreign key constraint error is triggered at runtime. - In MySQL versions 5.6 and later, and MariaDB versions before 10.5, attempting to create a table definition with the `SET DEFAULT` referential action fails with a syntax error. diff --git a/content/200-orm/300-prisma-migrate/200-understanding-prisma-migrate/200-shadow-database.mdx b/content/200-orm/300-prisma-migrate/200-understanding-prisma-migrate/200-shadow-database.mdx index ce27e645d4..e682866a9b 100644 --- a/content/200-orm/300-prisma-migrate/200-understanding-prisma-migrate/200-shadow-database.mdx +++ b/content/200-orm/300-prisma-migrate/200-understanding-prisma-migrate/200-shadow-database.mdx @@ -113,7 +113,7 @@ In order to create and delete the shadow database when using `migrate dev`, Pris | Database | Database user requirements | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | SQLite | No special requirements. | -| MySQL | Database user must have `CREATE, ALTER, DROP, REFERENCES ON *.*` privileges | +| MySQL/MariaDB | Database user must have `CREATE, ALTER, DROP, REFERENCES ON *.*` privileges | | PostgreSQL | The user must be a super user or have `CREATEDB` privilege. See `CREATE ROLE` ([PostgreSQL official documentation](https://www.postgresql.org/docs/12/sql-createrole.html)) | | Microsoft SQL Server | The user must be a site admin or have the `SERVER` securable. See the [official documentation](https://docs.microsoft.com/en-us/sql/relational-databases/security/permissions-database-engine?view=sql-server-ver15). | diff --git a/content/200-orm/500-reference/375-supported-databases.mdx b/content/200-orm/500-reference/375-supported-databases.mdx index 1a04c3eb9a..771acdaee4 100644 --- a/content/200-orm/500-reference/375-supported-databases.mdx +++ b/content/200-orm/500-reference/375-supported-databases.mdx @@ -19,14 +19,15 @@ An asterisk (\*) indicates that the version number is not relevant; either all v | Database | Version | | -------------------- | ------- | | CockroachDB | 21.2.4+ | -| MariaDB | 10 | +| MariaDB | 10.0+ | +| MariaDB | 11.0+ | | Microsoft SQL Server | 2017 | | Microsoft SQL Server | 2019 | | Microsoft SQL Server | 2022 | | MongoDB | 4.2+ | | MySQL | 5.6 | | MySQL | 5.7 | -| MySQL | 8 | +| MySQL | 8.0 | | PostgreSQL | 9.6 | | PostgreSQL | 10 | | PostgreSQL | 11 | diff --git a/content/300-accelerate/200-getting-started.mdx b/content/300-accelerate/200-getting-started.mdx index 70e096d373..fa0a24042f 100644 --- a/content/300-accelerate/200-getting-started.mdx +++ b/content/300-accelerate/200-getting-started.mdx @@ -16,7 +16,7 @@ To get started with Accelerate, you will need the following: - A GitHub account. - A project that uses [Prisma Client](/orm/prisma-client) `4.16.1` or higher. If your project is using interactive transactions, you need to use `5.1.1` or higher. (We always recommend using the latest version of Prisma.) -- A hosted PostgreSQL, MySQL, PlanetScale, CockroachDB, or MongoDB database. +- A hosted PostgreSQL, MySQL/MariaDB, PlanetScale, CockroachDB, or MongoDB database. ## 1. Enable Accelerate in a project diff --git a/src/components/shortcodes/index.tsx b/src/components/shortcodes/index.tsx index c4df9305cc..75634f02a9 100644 --- a/src/components/shortcodes/index.tsx +++ b/src/components/shortcodes/index.tsx @@ -32,6 +32,7 @@ import { Tab, } from './gettingstarted' import PostgresSQLSimple from '../../icons/technologies/PostgresSQLSimple' +import MariaDBDark from '../../icons/technologies/MariaDBDark' import MySQLSimple from '../../icons/technologies/MySQLSimple' import SQLServer from '../../icons/technologies/SQLServer' import PlanetScale from '../../icons/technologies/PlanetScale' @@ -93,6 +94,7 @@ const shortcodes = { Tab, SquareLogo, PostgresSQLSimple, + MariaDBDark, MySQLSimple, SQLServer, PlanetScale, From 0a60136e540012ea86a942f6d803e2e33dd41847 Mon Sep 17 00:00:00 2001 From: Nikolas Date: Thu, 21 Mar 2024 14:54:35 +0100 Subject: [PATCH 6/8] Update 050-raw-queries.mdx (#5730) * Update 050-raw-queries.mdx * Update content/200-orm/200-prisma-client/100-queries/090-raw-database-access/050-raw-queries.mdx --------- Co-authored-by: Jon Harrell <4829245+jharrell@users.noreply.github.com> --- .../100-queries/090-raw-database-access/050-raw-queries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 be7748b967..251d67d0bc 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 @@ -153,7 +153,7 @@ result.forEach((x) => { }) ``` -> **Note**: The Prisma Client query engine standardizes the return type for all databases. **Using the raw queries does not**. If the database provider is MySQL, the values are `1` or `0`. However, if the database provider is PostgreSQL, the values are `true`, `false`, or `NULL`. +For regular CRUD queries, the Prisma Client query engine standardizes the return type for all databases. **Using the raw queries does not**. If the database provider is MySQL, the returned values are `1` or `0`. However, if the database provider is PostgreSQL, the values are `true` or `false`. > **Note**: Prisma sends JavaScript integers to PostgreSQL as `INT8`. This might conflict with your user-defined functions that accept only `INT4` as input. If you use `$queryRaw` in conjunction with a PostgreSQL database, update the input types to `INT8`, or cast your query parameters to `INT4`. From ca47e46a83f1a8129632e02596b05326320e9dce Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Thu, 21 Mar 2024 21:00:31 +0600 Subject: [PATCH 7/8] feat: add troubleshooting guide for accelerate (#5731) * feat: add troubleshooting guide for accelerate * enhance: enhance the troubleshooting guide * fix refine indentation --- .../500-reference/250-error-reference.mdx | 6 + content/300-accelerate/500-limitations.mdx | 4 + content/300-accelerate/650-troubleshoot.mdx | 127 ++++++++++++++++++ 3 files changed, 137 insertions(+) create mode 100644 content/300-accelerate/650-troubleshoot.mdx diff --git a/content/200-orm/500-reference/250-error-reference.mdx b/content/200-orm/500-reference/250-error-reference.mdx index 65c4ef5499..ff968a5a33 100644 --- a/content/200-orm/500-reference/250-error-reference.mdx +++ b/content/200-orm/500-reference/250-error-reference.mdx @@ -474,6 +474,8 @@ The included usage of the current plan has been exceeded. This can only occur on The global timeout of Accelerate has been exceeded. You can find the limit [here](/accelerate/limitations#query-timeout-limit). +> Also see the [troubleshooting guide](/accelerate/troubleshoot#p6004-querytimeout) for more information. + #### P6005 (InvalidParameters) The user supplied invalid parameters. Currently only relevant for transaction methods. For example, setting a timeout that is too high. You can find the limit [here](/accelerate/limitations#interactive-transactions-query-timeout-limit). @@ -486,10 +488,14 @@ The chosen Prisma version is not compatible with Accelerate. This may occur when The engine failed to start. For example, it couldn't establish a connection to the database. +> Also see the [troubleshooting guide](/accelerate/troubleshoot#p6008-connectionerrorenginestarterror) for more information. + #### P6009 (ResponseSizeLimitExceeded) The global response size limit of Accelerate has been exceeded. You can find the limit [here](/accelerate/limitations#response-size-limit). +> Also see the [troubleshooting guide](/accelerate/troubleshoot#p6009-responsesizelimitexceeded) for more information. + ### Prisma Pulse Prisma Pulse-related errors start with P61xx. diff --git a/content/300-accelerate/500-limitations.mdx b/content/300-accelerate/500-limitations.mdx index dec1b870a6..e0921d4473 100644 --- a/content/300-accelerate/500-limitations.mdx +++ b/content/300-accelerate/500-limitations.mdx @@ -16,6 +16,8 @@ Below are descriptions of known limitations when using Accelerate. If you are aw Accelerate has a global timeout of `10s` for each query. Reach out to [support@prisma.io](mailto:support@prisma.io) with your use case if your application requires a greater timeout value. +> Also see the [troubleshooting guide](/accelerate/troubleshoot#p6004-querytimeout) for more information. + ## Interactive transactions query timeout limit Accelerate has a global timeout of `15s` for each [interactive transaction](/orm/prisma-client/queries/transactions#interactive-transactions). Reach out to [support@prisma.io](mailto:support@prisma.io) with your use case if your application requires a greater timeout value. @@ -24,6 +26,8 @@ Accelerate has a global timeout of `15s` for each [interactive transaction](/orm Accelerate has a global response size limit of `5MB`. Reach out to [support@prisma.io](mailto:support@prisma.io) with your use case if your application requires a larger response size. +> Also see the [troubleshooting guide](/accelerate/troubleshoot#p6009-responsesizelimitexceeded) for more information. + ## Cannot cache raw queries At the moment, it is not possible to cache the responses of [raw queries](/orm/prisma-client/queries/raw-database-access/raw-queries). diff --git a/content/300-accelerate/650-troubleshoot.mdx b/content/300-accelerate/650-troubleshoot.mdx new file mode 100644 index 0000000000..77034f6cec --- /dev/null +++ b/content/300-accelerate/650-troubleshoot.mdx @@ -0,0 +1,127 @@ +--- +title: 'Troubleshooting Guide' +metaTitle: 'Troubleshooting: Prisma Accelerate' +metaDescription: 'Troubleshooting Prisma Accelerate.' +tocDepth: 3 +toc: true +--- + + + +When working with Prisma Accelerate, you may encounter errors often highlighted by specific error codes during development and operations. It is important to understand the meaning of these errors, why they occur, and how to resolve them in order to ensure the smooth operation of your applications. This guide aims to provide insights and steps to troubleshoot specific error codes encountered with Prisma Accelerate. + + + +## [P6009](/orm/reference/error-reference#p6009-responsesizelimitexceeded) (ResponseSizeLimitExceeded) + +This error is triggered when the response size from a database query exceeds the 5MB limit. We've implemented this restriction to safeguard your application performance, as retrieving data over 5MB can significantly slow down your application due to multiple network layers. Typically, transmitting more than 5MB of data is common when conducting ETL (Extract, Transform, Load) operations. However, for other scenarios such as transactional queries, real-time data fetching for user interfaces, bulk data updates, or aggregating large datasets for analytics outside of ETL contexts, it should generally be avoided. These use cases, while essential, can often be optimised to work within the 5MB limit, ensuring smoother performance and a better user experience. + +### Possible causes for [P6009](/orm/reference/error-reference#p6009-responsesizelimitexceeded) + +#### Transmitting images/files in response + +This error may arise if images or files stored within your table are being fetched, resulting in a large response size. Storing assets directly in the database is generally discouraged because it significantly impacts database performance and scalability. In addition to performance, it makes database backups slow and significantly increases the cost of storing routine backups. + +**Suggested solution:** Store the image/file in a BLOB store like [Cloudflare R2](https://developers.cloudflare.com/r2/), [AWS S3](https://aws.amazon.com/pm/serv-s3/), [Cloudinary](https://cloudinary.com/), etc. These services would allow you to store the assets optimally and return a URL through which you should be able to access the asset. You can store this URL in your table instead of storing the asset directly in database. This would substantially reduce the size of your response. + +#### Overfetching of data + +In certain cases, a large number of records or fields are unintentionally fetched, which results in exceeding the 5MB limit. This could happen when the [`where`](/orm/reference/prisma-client-reference#where) clause in the query is incorrect or entirely missing. + +**Suggested solution:** Double-check if the `where` clause is filtering the data as you expect. Consider using [pagination](/orm/prisma-client/queries/pagination) to prevent a large number of records from being fetched. Additionally, use the [`select`](/orm/reference/prisma-client-reference#select) clause to return only the fields that are being consumed to further reduce the response size. + +#### Fetching a large volume of data + +In many data processing workflows, especially those involving ETL (Extract-Transform-Load) processes or scheduled CRON jobs, there's a need to extract large amounts of data from data sources (like databases, APIs, or file systems) for analysis, reporting, or further processing. If you are running an ETL/CRON workload that fetches a huge chunk of data for analytical processing then you might run into this limit. + +**Suggested solution:** Consider splitting your query to fetch data in batches to prevent the 5MB limit from being reached. By splitting your query to retrieve data in batches, you ensure that each operation fetches only a portion of the total data volume, thereby not exceeding the size limit for a single fetch operation. + +## [P6004](/orm/reference/error-reference#p6004-querytimeout) (QueryTimeout) + +This error occurs when a database query fails to return a response within 10 seconds. The 10-second limit includes the duration of waiting for a connection from the pool, network latency to the database, and the execution time of the query itself. We enforce this limit to prevent unintentional long-running queries that can overload system resources. + +> The time for Accelerate's cross-region networking is excluded from the 10-second limit. + +### Possible causes for [P6004](/orm/reference/error-reference#p6004-querytimeout) + +This error could be caused by numerous reasons. Some of the prominent ones are: + +#### High traffic and insufficient connections + +If the application is receiving very high traffic and there are not a sufficient number of connections available to the database, then the queries would need to wait for a connection to become available. This situation can lead to queries waiting longer than 10 seconds for a connection, ultimately triggering a timeout error if they do not get serviced within this duration. + +**Suggested solution**: Review and possibly increase the `connection_limit` specified in the connection string parameter when setting up Accelerate in a platform environment ([reference](/accelerate/connection-pooling#configuring-the-connection-pool-size)). +This limit should align with your database's maximum number of connections. + +By default, the connection limit is set to 10 unless a +different `connection_limit` is specified in your database connection string. + +#### Long-running queries + +Queries may be slow to respond, hitting the 10-second timeout even when connections are available. This could happen if a very large amount of data is being fetched in a single query or if appropriate indexes are missing from the table. + +**Suggested solution**: Identify the slow-running queries and fetch only the required data. If you only need to use specific fields from the table, then you can use the select clause in your queries to prevent unnecessary data from being fetched. Additionally, you could consider adding appropriate indexes based on the query to ensure that data is fetched efficiently. +You can also consider isolating long running queries into separate environments, so that these long running queries would not affect the transactional queries. + +#### Database resource contention + +A common yet challenging issue is when other services operating on the same database perform heavy analytics or data processing tasks, significantly consuming database resources. These operations can monopolize database connections and processing power, leading to a scenario where even simple queries cannot be executed in a timely manner. This "busy" or "noisy" database environment can cause queries that are typically fast to run slowly or even timeout, particularly during periods of high activity from other services. + +Users often rely on CPU and memory usage metrics to gauge database load, which can be misleading. While these are important indicators, they might not fully represent the database's operational state. Direct metrics like the number of reads, writes, and wait times offer a clearer view of the database's performance and should be monitored closely. A noticeable degradation in these metrics, especially in the absence of changes to the queries or data model, suggests that external pressures are affecting database performance. + +**Suggestion solution**: If normally quick queries are intermittently slow or timing out without any modifications to them, it's probable that competing queries are exerting pressure on the same database tables. To diagnose this, adopt monitoring tools or leverage your database's inherent capabilities to observe reads, writes, and wait times. Such monitoring will unveil activity patterns or spikes that align with the observed performance dips. + +Moreover, it's crucial to periodically scrutinize and refine essential queries and verify that tables are properly indexed. This proactive approach minimizes the vulnerability of these queries to slowdowns caused by competing workloads. + +### Considerations for [P6009](/orm/reference/error-reference#p6009-responsesizelimitexceeded) and [P6004](/orm/reference/error-reference#p6004-querytimeout) errors + +For runtimes that support Prisma ORM natively, you could consider creating two `PrismaClient` Instances. One with the Accelerate connection string (prefixed with `prisma://`) and the other one with the direct database connection string (prefixed with `postgres://`, `mysql://` etc). The main idea behind this approach is to bypass Accelerate for certain specific queries. + +However, please note that the available connections would be split between both of your `PrismaClient` Instances. It's crucial to understand the implications of managing multiple instances, particularly in regards to direct database connections. Utilizing a `PrismaClient` instance with a direct database connection string means that this connection will interact directly with your database. + +This approach requires careful consideration because the direct connections and those managed by Accelerate share the same underlying database connection pool. This can lead to competition for resources, potentially affecting the performance and availability of your database services. + +Additionally, direct connections could have a significant impact on your database's performance and availability. Operations that consume a considerable amount of resources could potentially degrade the service for other users or processes that rely on the same database. + +If your application's runtime environment supports Prisma ORM natively and you're considering this strategy to circumvent P6009 and P6004 errors, you might create two `PrismaClient` instances: + +1. An instance using the Accelerate connection string (prefixed with `prisma://`) for general operations. +2. Another instance with the direct database connection string (e.g., prefixed with `postgres://`, `mysql://`, etc.) for specific operations anticipated to exceed 10 seconds in execution time or to result in responses larger than 5MB. + +```jsx +export const prisma = new PrismaClient({ + datasourceUrl: process.env.DIRECT_DB_CONNECTION, +}) + +export const prismaAccelerate = new PrismaClient({ + datasourceUrl: process.env.ACCELERATE_CONNECTION, +}).$extends(withAccelerate()) +``` + +This setup allows you to strategically direct certain operations through the direct connection, mitigating the risk of encountering the aforementioned errors. However, this decision should be made with a comprehensive understanding of the potential consequences and an assessment of whether your database infrastructure can support this additional load without compromising overall performance and availability. + +> Also see [**why doesn’t Accelerate fall back to the direct connection string during a service disruption?**](/accelerate/faq#why-doesnt-accelerate-fall-back-to-the-direct-connection-string-during-a-service-disruption) + +## [P6008](/orm/reference/error-reference#p6008-connectionerrorenginestarterror) (ConnectionError|EngineStartError) + +This error indicates that Prisma Accelerate cannot establish a connection to your database, potentially due to several reasons. + +### Possible causes for [P6008](/orm/reference/error-reference#p6008-connectionerrorenginestarterror) + +#### Database Not Publicly accessible + +Prisma Accelerate currently requires the database to be publicly accessible. If your database is behind a VPC, or access is restricted to specific IP addresses, this error may occur. + +**Suggested solution:** Ensure your database is publicly accessible, if not, allow public access. Please note this is only an interim requirement, Static IPs are coming soon and will alleviate the need for complete public access if that’s not desirable. + +#### Unreachable Database Host/Port + +If the database’s server address (hostname) and port are incorrect or unreachable then you may encounter this error. + +**Suggested solution:** Verify the hostname/port of the database connection string that was provided while creating the Prisma Accelerate project. Additionally, attempt to connect to the database using a Database GUI tool (e.g., [Prisma Studio](https://www.prisma.io/studio), [TablePlus](https://tableplus.com/), or [DataGrip](https://www.jetbrains.com/datagrip/)) for further investigation. + +#### Incorrect username/password/database name + +This error can happen when the wrong credentials are provided to Prisma Accelerate, preventing it from establishing a connection to your database. + +**Suggested solution:** Verify the correctness of your database's username, password, and name in the connection string provided to Prisma Accelerate. Ensure that these credentials match those required by your database. Testing the connection using a direct database GUI tool can also help in confirming if the provided credentials are correct. From 4ce4b661e75e5fb811f3d44e55b936a027e659e3 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Fri, 22 Mar 2024 00:20:37 +0600 Subject: [PATCH 8/8] feat: remove "new" tag from platform environments (#5741) * feat: remove "new" tag from platform environments * Update content/500-platform/20-concepts/30-environments.mdx --- content/500-platform/20-concepts/30-environments.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/500-platform/20-concepts/30-environments.mdx b/content/500-platform/20-concepts/30-environments.mdx index d21256bc48..cb19c3148d 100644 --- a/content/500-platform/20-concepts/30-environments.mdx +++ b/content/500-platform/20-concepts/30-environments.mdx @@ -4,7 +4,7 @@ metaTitle: 'Platform Environments' metaDescription: 'Learn about Environments in Platform Console.' tocDepth: 3 toc: true -highlight: true +highlight: false ---