diff --git a/content/200-orm/050-overview/100-introduction/100-what-is-prisma.mdx b/content/200-orm/050-overview/100-introduction/100-what-is-prisma.mdx index 74c1a6db21..edad60df07 100644 --- a/content/200-orm/050-overview/100-introduction/100-what-is-prisma.mdx +++ b/content/200-orm/050-overview/100-introduction/100-what-is-prisma.mdx @@ -109,11 +109,11 @@ In this schema, you configure three things: - **Generator**: Indicates that you want to generate Prisma Client - **Data model**: Defines your application models -### The Prisma ORM data model +### The Prisma schema data model On this page, the focus is on the data model. You can learn more about [Data sources](/orm/prisma-schema/overview/data-sources) and [Generators](/orm/prisma-schema/overview/generators) on the respective docs pages. -#### Functions of Prisma ORM models +#### Functions of Prisma schema data models The data model is a collection of [models](/orm/prisma-schema/data-model/models#defining-models). A model has two major functions: @@ -245,7 +245,7 @@ As mentioned above, there are two ways for "getting" your data model into the Pr With **Prisma Migrate**, Prisma ORM's integrated database migration tool, the workflow looks as follows: -1. Manually adjust your [Prisma ORM data model](/orm/prisma-schema/data-model/models) +1. Manually adjust your [Prisma schema data model](/orm/prisma-schema/data-model/models) 1. Migrate your development database using the `prisma migrate dev` CLI command 1. Use Prisma Client in your application code to access your database diff --git a/content/200-orm/050-overview/100-introduction/250-should-you-use-prisma.mdx b/content/200-orm/050-overview/100-introduction/250-should-you-use-prisma.mdx index c9e3de6ba1..5847a6489d 100644 --- a/content/200-orm/050-overview/100-introduction/250-should-you-use-prisma.mdx +++ b/content/200-orm/050-overview/100-introduction/250-should-you-use-prisma.mdx @@ -28,7 +28,7 @@ No matter if you're a SQL newcomer or veteran, Prisma ORM will give you a signif Here are a couple of the guiding principles and general practices we apply when designing and building our tools: -- [make the right thing easy](https://www.jason.af/right-thing-easy-thing/) +- [make the right thing easy](https://git.io/right-thing-easy-thing) - [pit of success](https://blog.codinghorror.com/falling-into-the-pit-of-success/) - offer intelligent autocompletion where possible - build powerful editor extensions (e.g. for [VS Code](https://marketplace.visualstudio.com/items?itemName=Prisma.prisma)) diff --git a/content/200-orm/050-overview/300-prisma-in-your-stack/02-graphql.mdx b/content/200-orm/050-overview/300-prisma-in-your-stack/02-graphql.mdx index 660b92d107..a7e8ba6546 100644 --- a/content/200-orm/050-overview/300-prisma-in-your-stack/02-graphql.mdx +++ b/content/200-orm/050-overview/300-prisma-in-your-stack/02-graphql.mdx @@ -24,20 +24,20 @@ Note that a GraphQL schema can be written code-first or SDL-first. Check out thi The GraphQL schema and HTTP server are typically handled by separate libraries. Here is an overview of current GraphQL server tools and their purpose: | Library (npm package) | Purpose | Compatible with Prisma ORM | Prisma integration | -| :-------------------- | :-------------------------- | :--------------------- | :----------------------------------------------------------------------------- | -| `graphql` | GraphQL schema (code-first) | Yes | No | -| `graphql-tools` | GraphQL schema (SDL-first) | Yes | No | -| `type-graphql` | GraphQL schema (code-first) | Yes | [`typegraphql-prisma`](https://www.npmjs.com/package/typegraphql-prisma) | -| `nexus` | GraphQL schema (code-first) | Yes | [`nexus-prisma`](https://graphql-nexus.github.io/nexus-prisma) _Early Preview_ | -| `apollo-server` | HTTP server | Yes | n/a | -| `express-graphql` | HTTP server | Yes | n/a | -| `fastify-gql` | HTTP server | Yes | n/a | -| `graphql-yoga` | HTTP server | Yes | n/a | +| :-------------------- | :-------------------------- | :------------------------- | :----------------------------------------------------------------------------- | +| `graphql` | GraphQL schema (code-first) | Yes | No | +| `graphql-tools` | GraphQL schema (SDL-first) | Yes | No | +| `type-graphql` | GraphQL schema (code-first) | Yes | [`typegraphql-prisma`](https://www.npmjs.com/package/typegraphql-prisma) | +| `nexus` | GraphQL schema (code-first) | Yes | [`nexus-prisma`](https://graphql-nexus.github.io/nexus-prisma) _Early Preview_ | +| `apollo-server` | HTTP server | Yes | n/a | +| `express-graphql` | HTTP server | Yes | n/a | +| `fastify-gql` | HTTP server | Yes | n/a | +| `graphql-yoga` | HTTP server | Yes | n/a | In addition to these standalone and single-purpose libraries, there are several projects building integrated _application frameworks_: -| Framework | Stack | Built by | Prisma ORM | Description | -| :---------------------------------- | :-------- | :------------------------------------------------ | :--------------------- | :------------------------------------- | +| Framework | Stack | Built by | Prisma ORM | Description | +| :---------------------------------- | :-------- | :------------------------------------------------ | :------------------------- | :------------------------------------- | | [Redwood.js](https://redwoodjs.com) | Fullstack | [Tom Preston-Werner](https://github.com/mojombo/) | Built on top of Prisma ORM | _Bringing full-stack to the JAMstack._ | > **Note**: If you notice any GraphQL libraries/frameworks missing from the list, please let us know. diff --git a/content/200-orm/050-overview/500-databases/200-database-drivers.mdx b/content/200-orm/050-overview/500-databases/200-database-drivers.mdx index fee924c691..685935cf50 100644 --- a/content/200-orm/050-overview/500-databases/200-database-drivers.mdx +++ b/content/200-orm/050-overview/500-databases/200-database-drivers.mdx @@ -8,7 +8,7 @@ toc_max_heading_level: 4 ## Default built-in drivers -One of Prisma Client's components is the [Query Engine](/orm/more/under-the-hood/engines) . The Query Engine is responsible for transforming Prisma Client queries to SQL statements. The Query Engine connects to your database using the included drivers that don't require additional setup. The built-in drivers use TCP connections to connect to the database. +One of Prisma Client's components is the [Query Engine](/orm/more/under-the-hood/engines). The Query Engine is responsible for transforming Prisma Client queries to SQL statements. The Query Engine connects to your database via TCP using built-in drivers that don't require additional setup. ![Query flow from the user application to the database with Prisma Client](./images/drivers/qe-query-execution-flow.png) @@ -20,11 +20,13 @@ Prisma Client will use the Query Engine to transform the Prisma Client query to ![Query flow from the user application to the database using Prisma Client and driver adapters](./images/drivers/qe-query-engine-adapter.png) -There are 2 different types of driver adapters: +There are two different types of driver adapters: - [Database driver adapters](#database-driver-adapters) - [Serverless driver adapters](#serverless-driver-adapters) +> **Note**: Driver adapters enable [edge deployments](/orm/prisma-client/deployment/edge/overview) of applications that use Prisma ORM. + ### Database driver adapters You can connect to your database using a Node.js-based driver from Prisma Client using a database driver adapter. Prisma maintains the following database driver adapters: @@ -41,13 +43,13 @@ Prisma ORM maintains the following serverless driver adapters: - [Neon](/orm/overview/databases/neon#how-to-use-neons-serverless-driver-with-prisma-orm-preview) - [PlanetScale](/orm/overview/databases/planetscale#how-to-use-the-planetscale-serverless-driver-with-prisma-orm-preview) -## Community maintained database driver adapters +### Community-maintained database driver adapters You can also build your own driver adapter for the database you're using. The following is a list of community maintained driver adapters: - [TiDB](https://github.com/tidbcloud/prisma-adapter) -### How to use driver adapters +## How to use driver adapters To use this feature: @@ -72,6 +74,26 @@ To use this feature: - [PlanetScale](/orm/overview/databases/planetscale#how-to-use-the-planetscale-serverless-driver-with-prisma-orm-preview) - [Turso](/orm/overview/databases/turso#how-to-connect-and-query-a-turso-database) +## Notes about using driver adapters + +### Driver adapters don't read the connection string from the Prisma schema + +When using Prisma ORM's built-in drivers, the connection string is read from the `url` field of the `datasource` block in your Prisma schema. + +On the other hand, when using a driver adapter, the connection string needs to be provided in your _application code_ when the driver adapter is set up initially. Here is how this is done for the `pg` driver and the `@prisma/adapter-pg` adapter: + +```ts highlight=5,normal +import { PrismaClient } from '@prisma/client' +import { PrismaPg } from '@prisma/adapter-pg' +import { Pool } from 'pg' + +const pool = new Pool({ connectionString: env.DATABASE_URL }) +const adapter = new PrismaPg(pool) +const prisma = new PrismaClient({ adapter }) +``` + +See the docs for the driver adapter you're using for concrete setup instructions. + ### Driver adapters and custom output paths Since Prisma 5.9.0, when using the driver adapters Preview feature along with a [custom output path for Prisma Client](/orm/prisma-client/setup-and-configuration/generating-prisma-client#using-a-custom-output-path), you cannot reference Prisma Client using a relative path. 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 8f28e423df..4a58d67d81 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. @@ -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/050-overview/500-databases/600-mongodb.mdx b/content/200-orm/050-overview/500-databases/600-mongodb.mdx index b47fd100a4..4718d34cd9 100644 --- a/content/200-orm/050-overview/500-databases/600-mongodb.mdx +++ b/content/200-orm/050-overview/500-databases/600-mongodb.mdx @@ -106,7 +106,7 @@ There are a number of strategies you could use for migrating this schema: Then when you encounter a missing `phoneNumber`, the value will be coerced into `000-000-0000`. -- **"No breaking changes" updates**: this strategy builds on the first one, with further consensus amongst your team that you don't rename or delete fields, only add new fields, and always define the new fields as optional. This policy can be reenforced by adding checks in the CI/CD process to verify that there are no backwards-incompatible changes to the schema. +- **"No breaking changes" updates**: this strategy builds on the first one, with further consensus amongst your team that you don't rename or delete fields, only add new fields, and always define the new fields as optional. This policy can be reinforced by adding checks in the CI/CD process to verify that there are no backwards-incompatible changes to the schema. - **"All-at-once" updates**: this strategy is similar to traditional migrations in relational databases, where all data is updated to reflect the new schema. In the scenario above, you would create a script to add a value for the phone number field to all existing users in your database. You can then make the field a required field in the application because the schema and the data are consistent. @@ -562,9 +562,9 @@ MongoDB types that are currently unsupported: When introspecting a MongoDB database, Prisma ORM uses the relevant [scalar types](/orm/prisma-schema/data-model/models#scalar-fields). Some special types also get additional native type annotations: -| MongoDB (Type \| Aliases) | Prisma ORM| Supported | Native database type attribute | Notes | -| ------------------------- | -------- | :-------: | :----------------------------- | :---- | -| `objectId` | `String` | ✔️ | `@db.ObjectId` | | +| MongoDB (Type \| Aliases) | Prisma ORM | Supported | Native database type attribute | Notes | +| ------------------------- | ---------- | :-------: | :----------------------------- | :---- | +| `objectId` | `String` | ✔️ | `@db.ObjectId` | | [Introspection](/orm/prisma-schema/introspection) adds native database types that are **not yet supported** as [`Unsupported`](/orm/reference/prisma-schema-reference#unsupported) fields: 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 85% rename from content/200-orm/050-overview/500-databases/860-cockroachdb.mdx rename to content/200-orm/050-overview/500-databases/840-cockroachdb.mdx index e19c6aa486..9dba032f7e 100644 --- a/content/200-orm/050-overview/500-databases/860-cockroachdb.mdx +++ b/content/200-orm/050-overview/500-databases/840-cockroachdb.mdx @@ -22,9 +22,8 @@ The CockroachDB connector is generally available in versions `3.14.0` and later. CockroachDB is a distributed database that is designed for scalability and high availability. Features include: -- **Built-in scaling:** CockroachDB comes with automated replication, failover and repair capabilities to allow easy horizontal scaling of your application -- **Consistent transactions:** CockroachDB is a relational database that supports consistent transactions that maintain data integrity - **Compatibility with PostgreSQL:** CockroachDB is compatible with PostgreSQL, allowing interoperability with a large ecosystem of existing products +- **Built-in scaling:** CockroachDB comes with automated replication, failover and repair capabilities to allow easy horizontal scaling of your application ## Commonalities with other database providers @@ -134,24 +133,24 @@ The following table lists differences between CockroachDB and PostgreSQL: The CockroachDB connector maps the [scalar types](/orm/prisma-schema/data-model/models#scalar-fields) from the Prisma ORM [data model](/orm/prisma-schema/data-model/models) to native column types. These native types are mostly the same as for PostgreSQL — see the [Native type mapping from Prisma ORM to CockroachDB](#native-type-mapping-from-prisma-orm-to-cockroachdb) for details. However, there are some limitations: | CockroachDB (Type \| Aliases) | Prisma ORM | Supported | Native database type attribute | Notes | -| ----------------------------- | --------- | :-------: | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------- | -| `money` | `Decimal` | Not yet | `@db.Money` | Supported in PostgreSQL but [not currently in CockroachDB](https://github.com/cockroachdb/cockroach/issues/41578) | -| `xml` | `String` | Not yet | `@db.Xml` | Supported in PostgreSQL but [not currently in CockroachDB](https://github.com/cockroachdb/cockroach/issues/43355) | -| `jsonb` arrays | `Json[]` | Not yet | N/A | `Json[]` supported in PostgreSQL but [not currently in CockroachDB](https://github.com/cockroachdb/cockroach/issues/23468) | +| ----------------------------- | ---------- | :-------: | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------- | +| `money` | `Decimal` | Not yet | `@db.Money` | Supported in PostgreSQL but [not currently in CockroachDB](https://github.com/cockroachdb/cockroach/issues/41578) | +| `xml` | `String` | Not yet | `@db.Xml` | Supported in PostgreSQL but [not currently in CockroachDB](https://github.com/cockroachdb/cockroach/issues/43355) | +| `jsonb` arrays | `Json[]` | Not yet | N/A | `Json[]` supported in PostgreSQL but [not currently in CockroachDB](https://github.com/cockroachdb/cockroach/issues/23468) | ## Other limitations The following table lists any other current known limitations of CockroachDB compared to PostgreSQL: -| Issue | Area | Notes | -| ------------------------------------------------------------------------------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Primary keys are named `primary` instead of `TABLE_pkey`, the Prisma ORM default. | Introspection | This means that they are introspected as `@id(map: "primary")`. This will be [fixed in CockroachDB 22.1](https://github.com/cockroachdb/cockroach/pull/70604). | -| Foreign keys are named `fk_COLUMN_ref_TABLE` instead of `TABLE_COLUMN_fkey`, the Prisma ORM default. | Introspection | This means that they are introspected as `@relation([...], map: "fk_COLUMN_ref_TABLE")`. This will be [fixed in CockroachDB 22.1](https://github.com/cockroachdb/cockroach/pull/70658) | -| Index types `Hash`, `Gist`, `SpGist` or `Brin` are not supported. | Schema | In PostgreSQL, Prisma ORM allows [configuration of indexes](/orm/prisma-schema/data-model/indexes#configuring-the-access-type-of-indexes-with-type-postgresql) to use the different index access method. CockroachDB only currently supports `BTree` and `Gin`. | -| Pushing to `Enum` types not supported | Client | Pushing to `Enum` types (e.g. `data: { enum { push: "A" }, }`) is currently [not supported in CockroachDB](https://github.com/cockroachdb/cockroach/issues/71388) | -| Searching on `String` fields without a full text index not supported | Client | Searching on `String` fields without a full text index (e.g. `where: { text: { search: "cat & dog", }, },`) is currently [not supported in CockroachDB](https://github.com/cockroachdb/cockroach/issues/7821) | -| Integer division not supported | Client | Integer division (e.g. `data: { int: { divide: 10, }, }`) is currently [not supported in CockroachDB](https://github.com/cockroachdb/cockroach/issues/41448) | -| Limited filtering on `Json` fields | Client | Currently CockroachDB [only supports](https://github.com/cockroachdb/cockroach/issues/49144) `equals` and `not` filtering on `Json` fields | +| Issue | Area | Notes | +| ---------------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Primary keys are named `primary` instead of `TABLE_pkey`, the Prisma ORM default. | Introspection | This means that they are introspected as `@id(map: "primary")`. This will be [fixed in CockroachDB 22.1](https://github.com/cockroachdb/cockroach/pull/70604). | +| Foreign keys are named `fk_COLUMN_ref_TABLE` instead of `TABLE_COLUMN_fkey`, the Prisma ORM default. | Introspection | This means that they are introspected as `@relation([...], map: "fk_COLUMN_ref_TABLE")`. This will be [fixed in CockroachDB 22.1](https://github.com/cockroachdb/cockroach/pull/70658) | +| Index types `Hash`, `Gist`, `SpGist` or `Brin` are not supported. | Schema | In PostgreSQL, Prisma ORM allows [configuration of indexes](/orm/prisma-schema/data-model/indexes#configuring-the-access-type-of-indexes-with-type-postgresql) to use the different index access method. CockroachDB only currently supports `BTree` and `Gin`. | +| Pushing to `Enum` types not supported | Client | Pushing to `Enum` types (e.g. `data: { enum { push: "A" }, }`) is currently [not supported in CockroachDB](https://github.com/cockroachdb/cockroach/issues/71388) | +| Searching on `String` fields without a full text index not supported | Client | Searching on `String` fields without a full text index (e.g. `where: { text: { search: "cat & dog", }, },`) is currently [not supported in CockroachDB](https://github.com/cockroachdb/cockroach/issues/7821) | +| Integer division not supported | Client | Integer division (e.g. `data: { int: { divide: 10, }, }`) is currently [not supported in CockroachDB](https://github.com/cockroachdb/cockroach/issues/41448) | +| Limited filtering on `Json` fields | Client | Currently CockroachDB [only supports](https://github.com/cockroachdb/cockroach/issues/49144) `equals` and `not` filtering on `Json` fields | ## Type mapping between CockroachDB and the Prisma schema diff --git a/content/200-orm/050-overview/500-databases/850-planetscale.mdx b/content/200-orm/050-overview/500-databases/850-planetscale.mdx index 0e11507771..57b7c9f28d 100644 --- a/content/200-orm/050-overview/500-databases/850-planetscale.mdx +++ b/content/200-orm/050-overview/500-databases/850-planetscale.mdx @@ -37,12 +37,8 @@ Many aspects of using Prisma ORM with PlanetScale are just like using Prisma ORM PlanetScale's branching model and design for scalability means that there are also a number of differences to consider. You should be aware of the following points when deciding to use PlanetScale with Prisma ORM: - **Branching and deploy requests.** PlanetScale provides two types of database branches: _development branches_, which allow you to test out schema changes, and _production branches_, which are protected from direct schema changes. Instead, changes must be first created on a development branch and then deployed to production using a deploy request. Production branches are highly available and include automated daily backups. To learn more, see [How to use branches and deploy requests](#how-to-use-branches-and-deploy-requests). - -- **Referential actions and integrity.** To support scaling across multiple database servers, PlanetScale [does not allow the use of foreign key constraints](https://planetscale.com/docs/learn/operating-without-foreign-key-constraints), which are normally used in relational databases to enforce relationships between data in different tables, and asks users to handle this manually in their applications. - With Prisma ORM you can maintain these relationships in your data and allow the use of [referential actions](/orm/prisma-schema/data-model/relations/referential-actions) by using Prisma ORM's ability to [emulate relations in Prisma Client](/orm/prisma-schema/data-model/relations/relation-mode#emulate-relations-in-prisma-orm-with-the-prisma-relation-mode) with the `prisma` relation mode. For more information, see [How to emulate relations in Prisma Client](#how-to-emulate-relations-in-prisma-client). - -- **Creating indexes on foreign keys.** When emulating relations in Prisma ORM, you will need to create indexes on foreign keys. In a standard MySQL database, if a table has a column with a foreign key constraint, an index is automatically created on that column. Because PlanetScale does not support foreign keys, these indexes are [currently](https://github.com/prisma/prisma/issues/10611) not created when Prisma Client emulates relations, which can lead to issues with queries not being well optimised. To avoid this, you can create indexes in Prisma ORM. For more information, see [How to create indexes on foreign keys](#how-to-create-indexes-on-foreign-keys). - +- **Referential actions and integrity.** To support scaling across multiple database servers, PlanetScale [by default does not use foreign key constraints](https://planetscale.com/docs/learn/operating-without-foreign-key-constraints), which are normally used in relational databases to enforce relationships between data in different tables, and asks users to handle this manually in their applications. However, you can explicitly [enable them in the PlanetScale database settings](https://planetscale.com/docs/concepts/foreign-key-constraints). If you don't enable these explicitly, you can still maintain these relationships in your data and allow the use of [referential actions](/orm/prisma-schema/data-model/relations/referential-actions) by using Prisma ORM's ability to [emulate relations in Prisma Client](/orm/prisma-schema/data-model/relations/relation-mode#emulate-relations-in-prisma-orm-with-the-prisma-relation-mode) with the `prisma` relation mode. For more information, see [How to emulate relations in Prisma Client](#option-1-emulate-relations-in-prisma-client). +- **Creating indexes on foreign keys.** When [emulating relations in Prisma ORM](#option-1-emulate-relations-in-prisma-client) (i.e. when _not_ using foreign key constraints on the database-level), you will need to create dedicated indexes on foreign keys. In a standard MySQL database, if a table has a column with a foreign key constraint, an index is automatically created on that column. When PlanetScale is configured to not use foreign key constraints, these indexes are [currently](https://github.com/prisma/prisma/issues/10611) not created when Prisma Client emulates relations, which can lead to issues with queries not being well optimised. To avoid this, you can create indexes in Prisma ORM. For more information, see [How to create indexes on foreign keys](#2-create-indexes-on-foreign-keys). - **Making schema changes with `db push`.** When you merge a development branch into your production branch, PlanetScale will automatically compare the two schemas and generate its own schema diff. This means that Prisma ORM's [`prisma migrate`](/orm/prisma-migrate) workflow, which generates its own history of migration files, is not a natural fit when working with PlanetScale. These migration files may not reflect the actual schema changes run by PlanetScale when the branch is merged. @@ -53,7 +49,7 @@ PlanetScale's branching model and design for scalability means that there are al For an example of how this works, see [How to make schema changes with `db push`](#how-to-make-schema-changes-with-db-push) -- **Introspection**. When you introspect on an existing database, you will get a schema with no relations, as they are usually defined based on foreign keys that connect tables. Because PlanetScale does not support foreign keys, and you use Prisma ORM to emulate relations, you will need to add the missing relations in manually. For more information, see [How to add in missing relations after Introspection](#how-to-add-in-missing-relations-after-introspection). +- **Introspection**. When you introspect on an existing database and you have _not_ enabled [foreign key constraints in your PlanetScale database](#option-2-enable-foreign-key-constraints-in-the-planetscale-database-settings), you will get a schema with no relations, as they are usually defined based on foreign keys that connect tables. In that case, you will need to add the missing relations in manually. For more information, see [How to add in missing relations after Introspection](#how-to-add-in-missing-relations-after-introspection). ## How to use branches and deploy requests @@ -63,9 +59,15 @@ Every PlanetScale database is created with a branch called `main`, which is init If you try to push to a production branch, you will get the [error message](/orm/reference/error-reference#p3022) `Direct execution of DDL (Data Definition Language) SQL statements is disabled on this database.` -## How to emulate relations in Prisma Client +## How to use relations (and enable referential integrity) with PlanetScale + +### Option 1: Emulate relations in Prisma Client -PlanetScale does not allow foreign keys in its database schema. By default, Prisma ORM uses foreign keys in the underlying database to enforce relations between fields in your Prisma schema. In Prisma ORM versions 3.1.1 and later, you can [emulate relations in Prisma Client with the `prisma` relation mode](/orm/prisma-schema/data-model/relations/relation-mode#emulate-relations-in-prisma-orm-with-the-prisma-relation-mode), which avoids the need for foreign keys in the database. +#### 1. Set `relationMode = "prisma"` + +PlanetScale does not use foreign key constraints in its database schema by default. However, Prisma ORM relies on foreign key constraints in the underlying database to enforce referential integrity between models in your Prisma schema. + +In Prisma ORM versions 3.1.1 and later, you can [emulate relations in Prisma Client with the `prisma` relation mode](/orm/prisma-schema/data-model/relations/relation-mode#emulate-relations-in-prisma-orm-with-the-prisma-relation-mode), which avoids the need for foreign key constraints in the database. To enable emulation of relations in Prisma Client, set the `relationMode` field to `"prisma"` in the `datasource` block: @@ -83,11 +85,11 @@ The ability to set the relation mode was introduced as part of the `referentialI -If you use relations in your Prisma schema with the default `"foreignKeys"` option for the `referentialIntegrity` field, PlanetScale will error when Prisma ORM tries to create foreign keys. In versions 2.27.0 and later, Prisma ORM will output the [P3021 error message](/orm/reference/error-reference#p3021). +If you use relations in your Prisma schema with the default `"foreignKeys"` option for the `relationMode` field, PlanetScale will error and Prisma ORM output the [P3021 error message](/orm/reference/error-reference#p3021) when it tries to create foreign keys. (In versions before 2.27.0 it will output a raw database error.) -## How to create indexes on foreign keys +#### 2. Create indexes on foreign keys -When [you emulate relations in Prisma Client](#how-to-emulate-relations-in-prisma-client), you need to create your own indexes. As an example of a situation where you would want to add an index, take this schema for a blog with posts and comments: +When [you emulate relations in Prisma Client](#option-1-emulate-relations-in-prisma-client), you need to create your own indexes. As an example of a situation where you would want to add an index, take this schema for a blog with posts and comments: ```prisma file=schema.prisma showLineNumbers model Post { @@ -140,9 +142,41 @@ One issue to be aware of is that [implicit many-to-many relations](/orm/prisma-s +### Option 2: Enable foreign key constraints in the PlanetScale database settings + +Support for foreign key constraints in PlanetScale databases has been Generally Available since February 2024. Follow the instructions in the [PlanetScale documentation](https://planetscale.com/docs/concepts/foreign-key-constraints) to enable them in your database. + +You can then use Prisma ORM and define relations in your Prisma schema without the need for extra configuration. + +In that case, you can define a relation as with other database that supports foreign key constraints, for example: + +```prisma file=schema.prisma +model Post { + id Int @id @default(autoincrement()) + title String + content String + likes Int @default(0) + comments Comment[] +} + +model Comment { + id Int @id @default(autoincrement()) + comment String + postId Int + post Post @relation(fields: [postId], references: [id], onDelete: Cascade) +} +``` + +With this approach, it is _not_ necessary to: + +- set `relationMode = "prisma"` in your Prisma schema +- define additional indexes on foreign keys + +Also, introspection will automatically create relation fields in your Prisma schema because it can detect the foreign key constraints in the database. + ## How to make schema changes with `db push` -To use `db push` with PlanetScale, you will first need to [enable emulation of relations in Prisma Client](#how-to-emulate-relations-in-prisma-client). Pushing to your branch without referential emulation enabled will give the [error message](/orm/reference/error-reference#p3021) `Foreign keys cannot be created on this database.` +To use `db push` with PlanetScale, you will first need to [enable emulation of relations in Prisma Client](#option-1-emulate-relations-in-prisma-client). Pushing to your branch without referential emulation enabled will give the [error message](/orm/reference/error-reference#p3021) `Foreign keys cannot be created on this database.` As an example, let's say you decide to decide to add a new `excerpt` field to the blog post schema above. You will first need to [create a new development branch and connect to it](#how-to-use-branches-and-deploy-requests). @@ -181,6 +215,8 @@ For more examples, see PlanetScale's tutorial on [automatic migrations with Pris ## How to add in missing relations after Introspection +> **Note**: This section is only relevant if you use `relationMode = "prisma"` to emulate foreign key constraints with Prisma ORM. If you enabled foreign key constraints in your PlanetScale database, you can ignore this section. + After introspecting with `npx prisma db pull`, the schema you get may be missing some relations. For example, the following schema is missing a relation between the `User` and `Post` models: ```prisma file=schema.prisma showLineNumbers diff --git a/content/200-orm/050-overview/500-databases/880-supabase.mdx b/content/200-orm/050-overview/500-databases/880-supabase.mdx index 8a29604879..ec576ccaad 100644 --- a/content/200-orm/050-overview/500-databases/880-supabase.mdx +++ b/content/200-orm/050-overview/500-databases/880-supabase.mdx @@ -34,18 +34,18 @@ If you'd like to use the [connection pooling feature](https://supabase.com/docs/ ```env file=.env # Connect to Supabase via connection pooling with Supavisor. -DATABASE_URL="postgres://postgres.[your-supabase-project]:[password]@aws-0-eu-central-1.pooler.supabase.com:6543/postgres?pgbouncer=true" +DATABASE_URL="postgres://postgres.[your-supabase-project]:[password]@aws-0-[aws-region].pooler.supabase.com:6543/postgres?pgbouncer=true" ``` If you would like to use the Prisma CLI in order to perform other actions on your database (e.g. migrations) you will need to add a `DIRECT_URL` environment variable to use in the `datasource.directUrl` property so that the CLI can bypass Supavisor: ```env file=.env highlight=4-5;add showLineNumbers # Connect to Supabase via connection pooling with Supavisor. -DATABASE_URL="postgres://postgres.[your-supabase-project]:[password]@aws-0-eu-central-1.pooler.supabase.com:6543/postgres?pgbouncer=true" +DATABASE_URL="postgres://postgres.[your-supabase-project]:[password]@aws-0-[aws-region].pooler.supabase.com:6543/postgres?pgbouncer=true" //add-start # Direct connection to the database. Used for migrations. -DIRECT_URL="postgres://postgres:[password]@db.[your-supabase-project].supabase.co:5432/postgres" +DIRECT_URL="postgres://postgres.[your-supabase-project]:[password]@aws-0-[aws-region].pooler.supabase.com:5432/postgres" //add-end ``` diff --git a/content/200-orm/100-prisma-schema/10-overview/index.mdx b/content/200-orm/100-prisma-schema/10-overview/index.mdx index 9c237a4df8..490b12c2f1 100644 --- a/content/200-orm/100-prisma-schema/10-overview/index.mdx +++ b/content/200-orm/100-prisma-schema/10-overview/index.mdx @@ -127,7 +127,7 @@ The schema file is written in Prisma Schema Language (PSL). ### VS Code -Syntax highlighting for PSL is available via a [VS Code extension](https://marketplace.visualstudio.com/items?itemName=Prisma.prisma) (which also lets you auto-format the contents of your Prisma schema and indicates syntax errors with red squiggly lines). Learn more about [setting up Prisma in your editor](/orm/more/development-environment/editor-setup). +Syntax highlighting for PSL is available via a [VS Code extension](https://marketplace.visualstudio.com/items?itemName=Prisma.prisma) (which also lets you auto-format the contents of your Prisma schema and indicates syntax errors with red squiggly lines). Learn more about [setting up Prisma ORM in your editor](/orm/more/development-environment/editor-setup). ### GitHub 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 ca6fa88b53..c8cef27c85 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 @@ -1018,7 +1018,7 @@ model User { You can define enums in your data model [if enums are supported for your database connector](/orm/reference/database-features#misc), either natively or at Prisma ORM level. -Enums are considered [scalar](#scalar-fields) types in the Prisma data model. They're therefore [by default](/orm/prisma-client/queries/select-fields#return-the-default-selection-set) included as return values in [Prisma Client queries](/orm/prisma-client/queries/crud). +Enums are considered [scalar](#scalar-fields) types in the Prisma schema data model. They're therefore [by default](/orm/prisma-client/queries/select-fields#return-the-default-selection-set) included as return values in [Prisma Client queries](/orm/prisma-client/queries/crud). Enums are defined via the [`enum`](/orm/reference/prisma-schema-reference#enum) block. For example, a `User` has a `Role`: 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 2e22396732..e4098df4cf 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 @@ -171,9 +171,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/100-prisma-schema/20-data-model/20-relations/420-relation-mode.mdx b/content/200-orm/100-prisma-schema/20-data-model/20-relations/420-relation-mode.mdx index 8d45cb4483..43d7991877 100644 --- a/content/200-orm/100-prisma-schema/20-data-model/20-relations/420-relation-mode.mdx +++ b/content/200-orm/100-prisma-schema/20-data-model/20-relations/420-relation-mode.mdx @@ -96,7 +96,7 @@ The ability to set the relation mode was introduced as part of the `referentialI For relational databases, the available options are: - `foreignKeys`: this handles relations in the database with foreign keys. This is the default option for all relational database connectors and is active if no `relationMode` is explicitly set in the `datasource` block. -- `prisma`: this emulates relations in Prisma Client. You should also [enable this option](/orm/overview/databases/planetscale#how-to-emulate-relations-in-prisma-client) when you use the MySQL connector with a PlanetScale database. +- `prisma`: this emulates relations in Prisma Client. You should also [enable this option](/orm/overview/databases/planetscale#option-1-emulate-relations-in-prisma-client) when you use the MySQL connector with a PlanetScale database and don't have native foreign key constraints enabled in your PlanetScale database settings. For MongoDB, the only available option is the `prisma` relation mode. This mode is also active if no `relationMode` is explicitly set in the `datasource` block. @@ -110,7 +110,7 @@ If you switch between relation modes, Prisma ORM will add or remove foreign keys The `foreignKeys` relation mode handles relations in your relational database with foreign keys. This is the default option when you use a relational database connector (PostgreSQL, MySQL, SQLite, SQL Server, CockroachDB). -The `foreignKeys` relation mode is not available when you use the MongoDB connector. Some relational databases, [such as PlanetScale](/orm/overview/databases/planetscale#how-to-emulate-relations-in-prisma-client), also forbid the use of foreign keys. In these cases, you should instead [emulate relations in Prisma ORM with the `prisma` relation mode](#emulate-relations-in-prisma-orm-with-the-prisma-relation-mode). +The `foreignKeys` relation mode is not available when you use the MongoDB connector. Some relational databases, [such as PlanetScale](/orm/overview/databases/planetscale#option-1-emulate-relations-in-prisma-client), also forbid the use of foreign keys. In these cases, you should instead [emulate relations in Prisma ORM with the `prisma` relation mode](#emulate-relations-in-prisma-orm-with-the-prisma-relation-mode). ### Referential integrity @@ -138,7 +138,7 @@ When you apply changes to your Prisma schema with Prisma Migrate or `db push` wi The `prisma` relation mode emulates some foreign key constraints and referential actions for each Prisma Client query to maintain referential integrity, using some additional database queries and logic. -The `prisma` relation mode is the default option for the MongoDB connector. It should also be set if you use a relational database that does not support foreign keys. For example, [if you use PlanetScale](/orm/overview/databases/planetscale#how-to-emulate-relations-in-prisma-client) you should use the `prisma` relation mode. +The `prisma` relation mode is the default option for the MongoDB connector. It should also be set if you use a relational database that does not support foreign keys. For example, [if you use PlanetScale](/orm/overview/databases/planetscale#option-1-emulate-relations-in-prisma-client) without foreign key constraints, you should use the `prisma` relation mode. There are performance implications to emulation of referential integrity in diff --git a/content/200-orm/100-prisma-schema/20-data-model/80-table-inheritance.mdx b/content/200-orm/100-prisma-schema/20-data-model/80-table-inheritance.mdx index 01b16e206b..093cfa1481 100644 --- a/content/200-orm/100-prisma-schema/20-data-model/80-table-inheritance.mdx +++ b/content/200-orm/100-prisma-schema/20-data-model/80-table-inheritance.mdx @@ -254,7 +254,7 @@ const articles = await prisma.article.findMany({ Depending on your needs, you may also query the other way around by filtering on the `type` discriminator column: ```ts -// Query all articles +// Query all videos const videoActivities = await prisma.activity.findMany({ where: { type: 'Video' } include: { video: true } diff --git a/content/200-orm/100-prisma-schema/20-data-model/index.mdx b/content/200-orm/100-prisma-schema/20-data-model/index.mdx index 3ce02afbd9..ba1ec9f4d5 100644 --- a/content/200-orm/100-prisma-schema/20-data-model/index.mdx +++ b/content/200-orm/100-prisma-schema/20-data-model/index.mdx @@ -1,7 +1,7 @@ --- title: 'Data model' metaTitle: 'Data model' -metaDescription: 'Learn everything you need about the Prisma data model.' +metaDescription: 'Learn everything you need about the Prisma schema data model.' hide_table_of_contents: true --- diff --git a/content/200-orm/100-prisma-schema/50-introspection.mdx b/content/200-orm/100-prisma-schema/50-introspection.mdx index bb3d545ca2..ced22db9e0 100644 --- a/content/200-orm/100-prisma-schema/50-introspection.mdx +++ b/content/200-orm/100-prisma-schema/50-introspection.mdx @@ -49,7 +49,7 @@ Here's a high-level overview of the steps that `prisma db pull` performs interna 1. Read the [connection URL](/orm/reference/connection-urls) from the `datasource` configuration in the Prisma schema 1. Open a connection to the database 1. Introspect database schema (i.e. read tables, columns and other structures ...) -1. Transform database schema into Prisma data model +1. Transform database schema into Prisma schema data model 1. Write data model into Prisma schema or [update existing schema](#introspection-with-an-existing-schema) ## Introspection workflow @@ -67,7 +67,7 @@ Note that as you evolve the application, [this process can be repeated for an in ## Rules and conventions -Prisma ORM employs a number of conventions for translating a database schema into a Prisma data model: +Prisma ORM employs a number of conventions for translating a database schema into a data model in the Prisma schema: ### Model, field and enum names diff --git a/content/200-orm/200-prisma-client/000-setup-and-configuration/010-generating-prisma-client.mdx b/content/200-orm/200-prisma-client/000-setup-and-configuration/010-generating-prisma-client.mdx index aaf406b9d9..ef32c4bd8a 100644 --- a/content/200-orm/200-prisma-client/000-setup-and-configuration/010-generating-prisma-client.mdx +++ b/content/200-orm/200-prisma-client/000-setup-and-configuration/010-generating-prisma-client.mdx @@ -40,29 +40,29 @@ To generate and instantiate Prisma Client: 1. You can now [instantiate Prisma Client](instantiate-prisma-client) in your code: - + - + -```ts -import { PrismaClient } from '@prisma/client' -const prisma = new PrismaClient() -// use `prisma` in your application to read and write data in your DB -``` + ```ts + import { PrismaClient } from '@prisma/client' + const prisma = new PrismaClient() + // use `prisma` in your application to read and write data in your DB + ``` - + - + -```js -const { PrismaClient } = require('@prisma/client') -const prisma = new PrismaClient() -// use `prisma` in your application to read and write data in your DB -``` + ```js + const { PrismaClient } = require('@prisma/client') + const prisma = new PrismaClient() + // use `prisma` in your application to read and write data in your DB + ``` - + - + > **Important**: You need to re-run the `prisma generate` command after every change that's made to your Prisma schema to update the generated Prisma Client code. diff --git a/content/200-orm/200-prisma-client/100-queries/035-select-fields.mdx b/content/200-orm/200-prisma-client/100-queries/035-select-fields.mdx index 6fae7b247b..f43fccd414 100644 --- a/content/200-orm/200-prisma-client/100-queries/035-select-fields.mdx +++ b/content/200-orm/200-prisma-client/100-queries/035-select-fields.mdx @@ -19,7 +19,7 @@ To customize the result: Selecting only the fields and relations that you require rather than relying on the default selection set can ✔ reduce the size of the response and ✔ improve query speed. -Since version [5.9.0](https://github.com/prisma/prisma/releases/tag/5.9.0), when doing a relation query with `include` or by using `select` on a relation field, you can also specify the `relationLoadStrategy` to decide whether you want to use a database-level JOIN or perform multiple queries and merge the data on the application level. This feature is currently in [Preview](/orm/more/releases#preview), you can learn more about it [here](/orm/prisma-client/queries/relation-queries#relation-load-strategies-preview). +Since version [5.9.0](https://github.com/prisma/prisma/releases/tag/5.9.0), when doing a relation query with `include` or by using `select` on a relation field, you can also specify the `relationLoadStrategy` to decide whether you want to use a database-level join or perform multiple queries and merge the data on the application level. This feature is currently in [Preview](/orm/more/releases#preview), you can learn more about it [here](/orm/prisma-client/queries/relation-queries#relation-load-strategies-preview). diff --git a/content/200-orm/200-prisma-client/100-queries/037-relation-queries.mdx b/content/200-orm/200-prisma-client/100-queries/037-relation-queries.mdx index 535ff06a8f..5775494807 100644 --- a/content/200-orm/200-prisma-client/100-queries/037-relation-queries.mdx +++ b/content/200-orm/200-prisma-client/100-queries/037-relation-queries.mdx @@ -38,11 +38,11 @@ generator client { } ``` -After adding this flag, you need to run `prisma generate` again to re-generate Prisma Client. Also note that this feature is currently only available on PostgreSQL and CockroachDB for now. +After adding this flag, you need to run `prisma generate` again to re-generate Prisma Client. This feature is currently available on PostgreSQL, CockroachDB and MySQL. Prisma Client supports two load strategies for relations: -- `join` (default): Uses a database-level `LATERAL JOIN` and fetches all data with a single query to the database. +- `join` (default): Uses a database-level `LATERAL JOIN` (PostgreSQL) or correlated subqueries (MySQL) and fetches all data with a single query to the database. - `query`: Sends multiple queries to the database (one per table) and joins them on the application level. Another important difference between these two options is that the `join` strategy uses JSON aggregation on the database level. That means that it creates the JSON structures returned by Prisma Client already in the database which saves computation resources on the application level. @@ -77,10 +77,9 @@ const users = await prisma.user.findMany({ #### When to use which load strategy? -- The `join` strategy will be more effective in most scenarios. It uses a combination of `LATERAL JOINs` and JSON aggregation to reduce redundancy in result sets and delegate the work of transforming the query results into the expected JSON structures on the database server. +- The `join` strategy (default) will be more effective in most scenarios. On PostgreSQL, it uses a combination of `LATERAL JOINs` and JSON aggregation to reduce redundancy in result sets and delegate the work of transforming the query results into the expected JSON structures on the database server. On MySQL, it uses correlated subqueries to fetch the results with a single query. - There may be edge cases where `query` could be more performant depending on the characteristics of the dataset and query. We recommend that you profile your database queries to identify these situations. - Use `query` if you want to save resources on the database server and do heavy-lifting of merging and transforming data in the application server which might be easier to scale. -- Older database versions that don’t implement the `LATERAL` keyword may struggle require query complexity and data redundancy so that sending individual queries could be more performant. ### Include a relation 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 065281ecf8..431e389ad8 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 @@ -330,7 +330,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() @@ -338,12 +340,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. @@ -381,7 +380,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` @@ -416,7 +415,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/058-transactions.mdx b/content/200-orm/200-prisma-client/100-queries/058-transactions.mdx index 385bab6c01..0e9f47616a 100644 --- a/content/200-orm/200-prisma-client/100-queries/058-transactions.mdx +++ b/content/200-orm/200-prisma-client/100-queries/058-transactions.mdx @@ -9,8 +9,6 @@ tocDepth: 3 A database transaction refers to a sequence of read/write operations that are _guaranteed_ to either succeed or fail as a whole. This section describes the ways in which the Prisma Client API supports transactions. -For more in-depth examples and use cases, refer to the 📖 [transactions guide](/orm/prisma-client/queries/transactions). - ## Transactions overview @@ -90,8 +88,6 @@ const updatedPost: Post = await prisma.post.update({ }) ``` -> Refer to the 📖 [transactions guide](/orm/prisma-client/queries/transactions#nested-writes) for more examples. - ## Batch/bulk operations The following bulk operations run as transactions: @@ -100,7 +96,7 @@ The following bulk operations run as transactions: - `updateMany` - `createMany` -> Refer to the 📖 [transactions guide](/orm/prisma-client/queries/transactions#bulk-operations) for more examples. +> Refer to the section about [bulk operations](#bulk-operations) for more examples. ## The `$transaction` API @@ -173,7 +169,7 @@ Instead of immediately awaiting the result of each operation when it's performed > **Note**: Operations are executed according to the order they are placed in the transaction. Using a query in a transaction does not influence the order of operations in the query itself. > -> Refer to the 📖 [transactions guide](/orm/prisma-client/queries/transactions#transaction-api) for more examples. +> Refer to the section about the [transactions API](#transaction-api) for more examples. From version 4.4.0, the sequential operations transaction API has a second parameter. You can use the following optional configuration option in this parameter: @@ -207,7 +203,7 @@ If you use interactive transactions in preview from version 2.29.0 to 4.6.1 (inc -To use interactive transactions, you can pass an async function into [`$transaction`](/orm/prisma-client/queries/transactions#transaction-api). +To use interactive transactions, you can pass an async function into [`$transaction`](#transaction-api). The first argument passed into this async function is an instance of Prisma Client. Below, we will call this instance `tx`. Any Prisma Client call invoked on this `tx` instance is encapsulated into the transaction. @@ -816,7 +812,7 @@ await prisma.team.deleteMany({ #### Can I use bulk operations with the `$transaction([])` API? -Yes - for example, you can include multiple `deleteMany` operations inside a `$transaction([])`. +Yes — for example, you can include multiple `deleteMany` operations inside a `$transaction([])`. ### `$transaction([])` API @@ -1279,7 +1275,7 @@ It is now impossible for two people to book the same seat: If you have an existing application, it can be a significant undertaking to refactor your application to use optimistic concurrency control. Interactive Transactions offers a useful escape hatch for cases like this. -To create an interactive transaction, pass an async function into [$transaction](#transaction-api). +To create an interactive transaction, pass an async function into [$transaction](#transaction-api). The first argument passed into this async function is an instance of Prisma Client. Below, we will call this instance `tx`. Any Prisma Client call invoked on this `tx` instance is encapsulated into the transaction. diff --git a/content/200-orm/200-prisma-client/100-queries/060-full-text-search.mdx b/content/200-orm/200-prisma-client/100-queries/060-full-text-search.mdx index d461a7d7cc..605ff4ed9e 100644 --- a/content/200-orm/200-prisma-client/100-queries/060-full-text-search.mdx +++ b/content/200-orm/200-prisma-client/100-queries/060-full-text-search.mdx @@ -9,6 +9,8 @@ sidebar_class_name: preview-badge Prisma Client supports full-text search for **PostgreSQL** databases in versions 2.30.0 and later, and **MySQL** databases in versions 3.8.0 and later. With full-text search enabled, you can add search functionality to your application by searching for text within a database column. +> **Note**: There currently is a [known issue](https://github.com/prisma/prisma/issues/23627) in the full-text search feature. If you observe slow search queries, you can [optimize your query with raw SQL](#full-text-search-with-raw-sql). + ## Enabling full-text search @@ -29,7 +31,6 @@ The full-text search API is currently a Preview feature. To enable this feature, ```prisma file=schema.prisma highlight=3;add showLineNumbers generator client { provider = "prisma-client-js" - //add-next-line previewFeatures = ["fullTextSearch", "fullTextIndex"] } ``` @@ -244,3 +245,37 @@ const result = await prisma.blogs.findMany({ ``` However, if you try to search on `title` alone, the search will fail with the error "Cannot find a fulltext index to use for the search" and the message code is `P2030`, because the index requires a search on both fields. + +## Full-text search with raw SQL + +Full-text search is currently in Preview and due to a [known issue](https://github.com/prisma/prisma/issues/23627), you may be seeing slow search queries. If that's the case, you can optimize your query using [raw SQL](/orm/prisma-client/queries/raw-database-access). + +### PostgreSQL + +In PostgreSQL, you can use `to_tsvector` and `to_tsquery` to express your search query: + +```ts +const term = `cat` +const result = + await prisma.$queryRaw`SELECT * FROM "Blog" WHERE to_tsvector('english', "Blog"."content") @@ to_tsquery('english', ${term});` +``` + +> **Note**: Depending on your language preferences, you may exchange `english` against another language in the SQL statement. + +If you want to include a wildcard in your search term, you can do this as follows: + +```ts +const term = `cat:*` +const result = + await prisma.$queryRaw`SELECT * FROM "Blog" WHERE to_tsvector('english', "Blog"."content") @@ to_tsquery('english', ${term});` +``` + +### MySQL + +In MySQL, you can express your search query as follows: + +```ts +const term = `cat` +const result = + await prisma.$queryRaw`SELECT * FROM Blog WHERE MATCH(content) AGAINST(${term} IN NATURAL LANGUAGE MODE);` +``` 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 9e9e09dd5a..18dfba4619 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 @@ -23,10 +23,16 @@ Raw queries are available for all relational databases Prisma ORM supports. In a For relational databases, Prisma Client exposes four methods that allow you to send raw queries. You can use: -- `$queryRaw` to return actual records (for example, using `SELECT`) -- `$executeRaw` to return a count of affected rows (for example, after an `UPDATE` or `DELETE`) -- `$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** +- `$queryRaw` to return actual records (for example, using `SELECT`). +- `$executeRaw` to return a count of affected rows (for example, after an `UPDATE` or `DELETE`). +- `$queryRawUnsafe` to return actual records (for example, using `SELECT`) using a raw string. +- `$executeRawUnsafe` to return a count of affected rows (for example, after an `UPDATE` or `DELETE`) using a raw string. + +The methods with "Unsafe" in the name are a lot more flexible but are at **significant risk of making your code vulnerable to SQL injection**. + +The other two methods are safe to use with a simple template tag, no string building, and no concatenation. **However**, caution is required for more complex use cases as it is still possible to introduce SQL injection if these methods are used in certain ways. For more details, see the [SQL injection prevention](#sql-injection-prevention) section below. + +> **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` @@ -52,6 +58,12 @@ const result = await prisma.$queryRaw( ) ``` + + +If you use string building to incorporate untrusted input into queries passed to this method, then you open up the possibility for SQL injection attacks. SQL injection attacks can expose your data to modification or deletion. The prefered mechanism would be to include the text of the query at the point that you run this method. For more information on this risk and also examples of how to prevent it, see the [SQL injection prevention](#sql-injection-prevention) section below. + + + #### Considerations Be aware that: @@ -150,7 +162,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`. @@ -173,7 +185,7 @@ The `$queryRawUnsafe` method allows you to pass a raw string (or template string 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.

-We strongly advise that you use the `$queryRaw` query instead. For more information on SQL injection attacks, see the [OWASP SQL Injection guide](https://www.owasp.org/index.php/SQL_Injection). +Wherever possible you should use the `$queryRaw` method instead. When used correctly `$queryRaw` method is significantly safer but note that the `$queryRaw` method can also be made vulnerable in certain circumstances. For more information, see the [SQL injection prevention](#sql-injection-prevention) section below. @@ -197,62 +209,14 @@ prisma.$queryRawUnsafe( > **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 a parameterized `$queryRawUnsafe` query in conjunction with a PostgreSQL database, update the input types to `INT8`, or cast your query parameters to `INT4`. +For more details on using parameterized queries, see the [parameterized queries](#parameterized-queries) section below. + #### Signature ```ts no-lines $queryRawUnsafe(query: string, ...values: any[]): PrismaPromise; ``` -#### Parameterized queries - -As an alternative to tagged templates, `$queryRawUnsafe` supports standard parameterized queries where each variable is represented by a symbol (`?` for mySQL, `$1`, `$2`, and so on for PostgreSQL). The following example uses a MySQL query: - -```ts -const userName = 'Sarah' -const email = 'sarah@prisma.io' -const result = await prisma.$queryRawUnsafe( - 'SELECT * FROM User WHERE (name = ? OR email = ?)', - userName, - email -) -``` - -> **Note**: MySQL variables are represented by `?` - -The following example uses a PostgreSQL query: - -```ts -const userName = 'Sarah' -const email = 'sarah@prisma.io' -const result = await prisma.$queryRawUnsafe( - 'SELECT * FROM User WHERE (name = $1 OR email = $2)', - userName, - email -) -``` - -> **Note**: PostgreSQL variables are represented by `$1` and `$2` - -As with tagged templates, Prisma Client escapes all variables. - -> **Note**: You cannot pass a table or column name as a variable into a parameterized query. For example, you cannot `SELECT ?` and pass in `*` or `id, name` based on some condition. - -##### Parameterized PostgreSQL `ILIKE` query - -When you use `ILIKE`, the `%` wildcard character(s) should be included in the variable itself, not the query (`string`): - -```ts -const userName = 'Sarah' -const emailFragment = 'prisma.io' -const result = await prisma.$queryRawUnsafe( - 'SELECT * FROM "User" WHERE (name = $1 OR email ILIKE $2)', - userName, - `%${emailFragment}` -) -``` - -> **Note**: Using `%$2` as an argument would not work - ### `$executeRaw` `$executeRaw` returns the _number of rows affected by a database operation_, such as `UPDATE` or `DELETE`. This function does **not** return database records. The following query updates records in the database and returns a count of the number of records that were updated: @@ -272,6 +236,14 @@ const result: number = await prisma.$executeRaw`UPDATE User SET active = ${active} WHERE emailValidated = ${emailValidated};` ``` + + +If you use string building to incorporate untrusted input into queries passed to this method, then you open up the possibility for SQL injection attacks. SQL injection attacks can expose your data to modification or deletion. The prefered mechanism would be to include the text of the query at the point that you run this method. For more information on this risk and also examples of how to prevent it, see the [SQL injection prevention](#sql-injection-prevention) section below. + + + +#### Considerations + Be aware that: - `$executeRaw` does not support multiple queries in a single string (for example, `ALTER TABLE` and `CREATE TABLE` together). @@ -322,13 +294,11 @@ $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.

-We strongly advise that you use the `$executeRaw` query instead. For more information on SQL injection attacks, see the [OWASP SQL Injection guide](https://www.owasp.org/index.php/SQL_Injection). +Wherever possible you should use the `$executeRaw` method instead. When used correctly `$executeRaw` method is significantly safer but note that the `$executeRaw` method can also be made vulnerable in certain circumstances. For more information, see the [SQL injection prevention](#sql-injection-prevention) section below. @@ -353,6 +323,8 @@ const result = prisma.$executeRawUnsafe( ) ``` +For more details on using parameterized queries, see the [parameterized queries](#parameterized-queries) section below. + #### Signature ```ts no-lines @@ -549,22 +521,184 @@ The database will thus provide a `String` representation of your data which Pris For details of supported Prisma types, see the [Prisma connector overview](/orm/overview/databases) for the relevant database. -### SQL injection +## SQL injection prevention -Prisma Client mitigates the risk of SQL injection in the following ways: +The ideal way to avoid SQL injection in Prisma Client is to use the ORM models to perform queries wherever possible. -- Prisma Client escapes all variables when you use tagged templates and sends all queries as prepared statements. +Where this is not possible and raw queries are required, Prisma Client provides various raw methods, but it is important to use these methods safely. - ```ts - $queryRaw`...` // Tagged template - $executeRaw`...` // Tagged template - ``` +This section will provide various examples of using these methods safely and unsafely. You can test these examples in the [Prisma Playground](https://playground.prisma.io/examples). -- `$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`. +### In `$queryRaw` and `$executeRaw` -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**. +#### Simple, safe use of `$queryRaw` and `$executeRaw` -#### ⚠️ String concatenation +These methods can mitigate the risk of SQL injection by escaping all variables when you use tagged templates and sends all queries as prepared statements. + +```ts +$queryRaw`...` // Tagged template +$executeRaw`...` // Tagged template +``` + +The following example is safe ✅ from SQL Injection: + +```ts +const inputString = `'Sarah' UNION SELECT id, title FROM "Post"` +const result = + await prisma.$queryRaw`SELECT id, name FROM "User" WHERE name = ${inputString}` + +console.log(result) +``` + +#### Unsafe use of `$queryRaw` and `$executeRaw` + +However, it is also possible to use these methods in unsafe ways. + +One way is by artificially generating a tagged template that unsafely concatenates user input. + +The following example is vulnerable ❌ to SQL Injection: + +```ts +// Unsafely generate query text +const inputString = `'Sarah' UNION SELECT id, title FROM "Post"` // SQL Injection +const query = `SELECT id, name FROM "User" WHERE name = ${inputString}` + +// Version for Typescript +const stringsArray: any = [...[query]] + +// Version for Javascript +const stringsArray = [...[query]] + +// Use the `raw` property to impersonate a tagged template +stringsArray.raw = [query] + +// Use queryRaw +const result = await prisma.$queryRaw(stringsArray) +console.log(result) +``` + +Another way to make these methods vulnerable is misuse of the `Prisma.raw` function. + +The following examples are all vulnerable ❌ to SQL Injection: + +```ts +const inputString = `'Sarah' UNION SELECT id, title FROM "Post"` +const result = + await prisma.$queryRaw`SELECT id, name FROM "User" WHERE name = ${Prisma.raw( + inputString + )}` +console.log(result) +``` + +```ts +const inputString = `'Sarah' UNION SELECT id, title FROM "Post"` +const result = await prisma.$queryRaw( + Prisma.raw(`SELECT id, name FROM "User" WHERE name = ${inputString}`) +) +console.log(result) +``` + +```ts +const inputString = `'Sarah' UNION SELECT id, title FROM "Post"` +const query = Prisma.raw( + `SELECT id, name FROM "User" WHERE name = ${inputString}` +) +const result = await prisma.$queryRaw(query) +console.log(result) +``` + +#### Safely using `$queryRaw` and `$executeRaw` in more complex scenarios + +##### Building raw queries separate to query execution + +If you want to build your raw queries elsewhere or separate to your parameters you will need to use one of the following methods. + +In this example, the `sql` helper method is used to build the query text by safely including the variable. It is safe ✅ from SQL Injection: + +```ts +// inputString can be untrusted input +const inputString = `'Sarah' UNION SELECT id, title FROM "Post"` + +// Safe if the text query below is completely trusted content +const query = Prisma.sql`SELECT id, name FROM "User" WHERE name = ${inputString}` + +const result = await prisma.$queryRaw(query) +console.log(result) +``` + +In this example which is safe ✅ from SQL Injection, the `sql` helper method is used to build the query text including a parameter marker for the input value. Each variable is represented by a marker symbol (`?` for mySQL, `$1`, `$2`, and so on for PostgreSQL). Note that the examples just show PostgreSQL queries. + +```ts +// Version for Typescript +const query: any + +// Version for Javascript +const query + +// Safe if the text query below is completely trusted content +query = Prisma.sql`SELECT id, name FROM "User" WHERE name = $1` + +// inputString can be untrusted input +const inputString = `'Sarah' UNION SELECT id, title FROM "Post"` +query.values = [inputString] + +const result = await prisma.$queryRaw(query) +console.log(result) +``` + +> **Note**: PostgreSQL variables are represented by `$1`, etc + +##### Building raw queries elsewhere or in stages + +If you want to build your raw queries somewhere other than where the query is executed, the ideal way to do this is to create an `Sql` object from the segments of your query and pass it the parameter value. + +In the following example we have two variables to parameterize. The example is safe ✅ from SQL Injection as long as the query strings being passed to `Prisma.sql` only contain trusted content: + +```ts +// Example is safe if the text query below is completely trusted content +const query1 = `SELECT id, name FROM "User" WHERE name = ` // The first parameter would be inserted after this string +const query2 = ` OR name = ` // The second parameter would be inserted after this string + +const inputString1 = "Fred" +const inputString2 = `'Sarah' UNION SELECT id, title FROM "Post"` + +const query = Prisma.sql([query1, query2, ""], inputString1, inputString2) +const result = await prisma.$queryRaw(query); +console.log(result); +``` + +> Note: Notice that the string array being passed as the first parameter `Prisma.sql` needs to have an empty string at the end as the `sql` function expects one more query segment than the number of parameters. + +If you want to build your raw queries into one large string, this is still possible but requires some care as it is uses the potentially dangerous `Prisma.raw` method. You also need to build your query using the correct parameter markers for your database as Prisma won't be able to provide markers for the relevant database as it usually is. + +The following example is safe ✅ from SQL Injection as long as the query strings being passed to `Prisma.raw` only contain trusted content: + +```ts +// Version for Typescript +const query: any + +// Version for Javascript +const query + +// Example is safe if the text query below is completely trusted content +const query1 = `SELECT id, name FROM "User" ` +const query2 = `WHERE name = $1 ` + +query = Prisma.raw(`${query1}${query2}`) + +// inputString can be untrusted input +const inputString = `'Sarah' UNION SELECT id, title FROM "Post"` +query.values = [inputString] + +const result = await prisma.$queryRaw(query) +console.log(result) +``` + +### In `$queryRawUnsafe` and `$executeRawUnsafe` + +#### Using `$queryRawUnsafe` and `$executeRawUnsafe` unsafely + +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 these functions make it much more likely that your code will be vulnerable to SQL injection**. The following example concatenates `query` and `inputString`. Prisma Client ❌ **cannot** escape `inputString` in this example, which makes it vulnerable to SQL injection: @@ -576,6 +710,44 @@ const result = await prisma.$queryRawUnsafe(query) console.log(result) ``` +#### Parameterized queries + +As an alternative to tagged templates, `$queryRawUnsafe` supports standard parameterized queries where each variable is represented by a symbol (`?` for mySQL, `$1`, `$2`, and so on for PostgreSQL). Note that the examples just show PostgreSQL queries. + +The following example is safe ✅ from SQL Injection: + +```ts +const userName = 'Sarah' +const email = 'sarah@prisma.io' +const result = await prisma.$queryRawUnsafe( + 'SELECT * FROM User WHERE (name = $1 OR email = $2)', + userName, + email +) +``` + +> **Note**: PostgreSQL variables are represented by `$1` and `$2` + +As with tagged templates, Prisma Client escapes all variables when they are provided in this way. + +> **Note**: You cannot pass a table or column name as a variable into a parameterized query. For example, you cannot `SELECT ?` and pass in `*` or `id, name` based on some condition. + +##### Parameterized PostgreSQL `ILIKE` query + +When you use `ILIKE`, the `%` wildcard character(s) should be included in the variable itself, not the query (`string`). This example is safe ✅ from SQL Injection. + +```ts +const userName = 'Sarah' +const emailFragment = 'prisma.io' +const result = await prisma.$queryRawUnsafe( + 'SELECT * FROM "User" WHERE (name = $1 OR email ILIKE $2)', + userName, + `%${emailFragment}` +) +``` + +> **Note**: Using `%$2` as an argument would not work + ## Raw queries with MongoDB For MongoDB in versions `3.9.0` and later, Prisma Client exposes three methods that allow you to send raw queries. You can use: diff --git a/content/200-orm/200-prisma-client/100-queries/090-raw-database-access/index.mdx b/content/200-orm/200-prisma-client/100-queries/090-raw-database-access/index.mdx index 5551354b88..7af1631f05 100644 --- a/content/200-orm/200-prisma-client/100-queries/090-raw-database-access/index.mdx +++ b/content/200-orm/200-prisma-client/100-queries/090-raw-database-access/index.mdx @@ -7,7 +7,7 @@ hide_table_of_contents: true -While Prisma ORM aims to make all your database queries intuitive, type-safe, and convenient, there may be situations where you need to drop down to raw queries. +While Prisma ORM aims to make all your database queries intuitive, type-safe, and convenient, there may be situations where you need to drop down to raw queries. This may happen for several reasons, e.g., because you need to optimize the performance of a specific query or because your data requirements can't be expressed by Prisma Client's query API. diff --git a/content/200-orm/200-prisma-client/500-deployment/201-serverless/400-deploy-to-aws-lambda.mdx b/content/200-orm/200-prisma-client/500-deployment/201-serverless/400-deploy-to-aws-lambda.mdx index 4bd7badaf0..f361dfcf0b 100644 --- a/content/200-orm/200-prisma-client/500-deployment/201-serverless/400-deploy-to-aws-lambda.mdx +++ b/content/200-orm/200-prisma-client/500-deployment/201-serverless/400-deploy-to-aws-lambda.mdx @@ -27,12 +27,27 @@ This section covers changes you will need to make to your application, regardles ### Define binary targets in Prisma Schema -The Prisma schema should contain the following in the `generator` block: +Depending on the version of Node.js, your Prisma schema should contain either `rhel-openssl-1.0.x` or `rhel-openssl-3.0.x` in the `generator` block: + + + + ```prisma binaryTargets = ["native", "rhel-openssl-1.0.x"] ``` + + + +```prisma +binaryTargets = ["native", "rhel-openssl-3.0.x"] +``` + + + + + This is necessary because the runtimes used in development and deployment differ. Add the [`binaryTarget`](/orm/reference/prisma-schema-reference#binarytargets-options) to make the compatible Prisma ORM engine file available. #### Lambda functions with arm64 architectures diff --git a/content/200-orm/200-prisma-client/500-deployment/201-serverless/500-deploy-to-netlify.mdx b/content/200-orm/200-prisma-client/500-deployment/201-serverless/500-deploy-to-netlify.mdx index dd0ce2ae1f..db0e516487 100644 --- a/content/200-orm/200-prisma-client/500-deployment/201-serverless/500-deploy-to-netlify.mdx +++ b/content/200-orm/200-prisma-client/500-deployment/201-serverless/500-deploy-to-netlify.mdx @@ -20,12 +20,27 @@ Before you can follow this guide, you will need to set up your application to be Since your code is being deployed to Netlify's environment, which isn't necessarily the same as your development environment, you will need to set [`binaryTargets`](/orm/reference/prisma-schema-reference#binarytargets-options) in order to download the query engine that is compatible with the Netlify runtime during your build step. If you do not set this option, your deployed code will have an incorrect query engine deployed with it and will not function. -You should update your Prisma schema to contain the following in the `generator` block: +Depending on the version of Node.js, your Prisma schema should contain either `rhel-openssl-1.0.x` or `rhel-openssl-3.0.x` in the `generator` block: + + + + ```prisma binaryTargets = ["native", "rhel-openssl-1.0.x"] ``` + + + +```prisma +binaryTargets = ["native", "rhel-openssl-3.0.x"] +``` + + + + + ## Store environment variables in Netlify We recommend keeping `.env` files in your `.gitignore` in order to prevent leakage of sensitives connection strings. Instead, you can use the Netlify CLI to [import values into netlify directly](https://docs.netlify.com/environment-variables/get-started/#import-variables-with-the-netlify-cli). diff --git a/content/200-orm/200-prisma-client/500-deployment/301-edge/100-overview.mdx b/content/200-orm/200-prisma-client/500-deployment/301-edge/100-overview.mdx new file mode 100644 index 0000000000..39968bf4b5 --- /dev/null +++ b/content/200-orm/200-prisma-client/500-deployment/301-edge/100-overview.mdx @@ -0,0 +1,60 @@ +--- +title: 'Overview (Deploy Prisma ORM at the Edge)' +sidebar_label: 'Overview' +metaDescription: 'Learn how to deploy your Prisma-backed apps to edge functions like Cloudflare Workers or Vercel Edge Functions' +tocDepth: 2 +--- + + + +## Deploying edge functions with Prisma ORM + +You can deploy an application that uses Prisma ORM to the edge. Depending on which edge function provider and which database you use, there are different considerations and things to be aware of. + +Here is a brief overview of all the edge function providers that are currently supported by Prisma ORM: + +| Provider / Product | Supported natively with Prisma ORM | Supported with Prisma Accelerate | +| ---------------------- | ------------------------------------------------------- | -------------------------------- | +| Vercel Edge Functions | ✅ (Preview; only compatible drivers) | ✅ | +| Vercel Edge Middleware | ✅ (Preview; only compatible drivers) | ✅ | +| Cloudflare Workers | ✅ (Preview; only compatible drivers) | ✅ | +| Cloudflare Pages | ✅ (Preview; only compatible drivers) | ✅ | +| Deno Deploy | [Not yet](https://github.com/prisma/prisma/issues/2452) | ✅ | + +Deploying edge functions that use Prisma ORM on Cloudflare and Vercel is currently in [Preview](/orm/more/releases#preview). + +## Edge-compatibility of database drivers + +### Why are there limitations around database drivers in edge functions? + +Edge functions typically don't use the standard Node.js runtime. For example, Vercel Edge Functions and Cloudflare Workers are running code in [V8 isolates](https://v8docs.nodesource.com/node-0.8/d5/dda/classv8_1_1_isolate.html). Deno Deploy is using the [Deno](https://deno.com/) JavaScript runtime. As a consequence, these edge functions only have access to a small subset of the standard Node.js APIs and also have constrained computing resources (CPU and memory). + +In particular, the constraint of not being able to freely open TCP connections makes it difficult to talk to a traditional database from an edge function. While Cloudflare has introduced a [`connect()`](https://developers.cloudflare.com/workers/runtime-apis/tcp-sockets/) API that enables limited TCP connections, this still only enables database access using specific database drivers that are compatible with that API. + +> **Note**: [Prisma Accelerate](/accelerate) enables you to access _any_ database from _any_ edge function provider. No edge-compatible driver is necessary. + +### Which database drivers are edge-compatible? + +Here is an overview of the different database drivers and their compatibility with different edge function offerings: + +- [Neon Serverless](https://neon.tech/docs/serverless/serverless-driver) uses HTTP to access the database. It works with Cloudflare Workers and Vercel Edge Functions. +- [PlanetScale Serverless](https://planetscale.com/docs/tutorials/planetscale-serverless-driver) uses HTTP to access the database. It works with Cloudflare Workers and Vercel Edge Functions. +- [`node-postgres`](https://node-postgres.com/) (`pg`) uses Cloudflare's `connect()` (TCP) to access the database. It is only compatible with Cloudflare Workers, not with Vercel Edge Functions. +- [`@libsql/client`](https://github.com/tursodatabase/libsql-client-ts) is used to access Turso databases. It works with Cloudflare Workers and Vercel Edge Functions. + +There's [also work being done](https://github.com/sidorares/node-mysql2/pull/2289) on the `node-mysql2` driver which will enable access to traditional MySQL databases from Cloudflare Workers and Pages in the future as well. + +You can use all of these drivers with Prisma ORM using the respective [driver adapters](/orm/overview/databases/database-drivers). + +Depending on which deployment provider and database/driver you use, there may be special considerations. Please take a look at the deployment docs for your respective scenario to make sure you can deploy your application successfully: + +- Cloudflare + - [PostgreSQL (traditional)](/orm/prisma-client/deployment/edge/deploy-to-cloudflare#postgresql-traditional) + - [PlanetScale](/orm/prisma-client/deployment/edge/deploy-to-cloudflare#planetscale) + - [Neon](/orm/prisma-client/deployment/edge/deploy-to-cloudflare#neon) +- Vercel + - [Vercel Postgres](/orm/prisma-client/deployment/edge/deploy-to-vercel#vercel-postgres) + - [Neon](/orm/prisma-client/deployment/edge/deploy-to-vercel#neon) + - [PlanetScale](/orm/prisma-client/deployment/edge/deploy-to-vercel#planetscale) + +If you want to deploy an app using Turso, you can follow the instructions [here](/orm/overview/databases/turso). diff --git a/content/200-orm/200-prisma-client/500-deployment/301-edge/450-deploy-to-cloudflare.mdx b/content/200-orm/200-prisma-client/500-deployment/301-edge/450-deploy-to-cloudflare.mdx new file mode 100644 index 0000000000..3657cf5281 --- /dev/null +++ b/content/200-orm/200-prisma-client/500-deployment/301-edge/450-deploy-to-cloudflare.mdx @@ -0,0 +1,541 @@ +--- +title: 'Deploy to Cloudflare Workers & Pages' +sidebar_label: Deploy to Cloudflare +metaTitle: 'Deploy to Cloudflare Workers & Pages' +metaDescription: 'Learn the things you need to know in order to deploy an app that uses Prisma Client for talking to a database to a Cloudflare Worker or to Cloudflare Pages.' +tocDepth: 3 +sidebar_class_name: preview-badge +--- + + + +This page covers everything you need to know to deploy an app with Prisma ORM to a [Cloudflare Worker](https://developers.cloudflare.com/workers/) or to [Cloudflare Pages](https://developers.cloudflare.com/pages). + + + +## General considerations when deploying to Cloudflare Workers + +This section covers _general_ things you need to be aware of when deploying to Cloudflare Workers or Pages and are using Prisma ORM, regardless of the database provider you use. + +### Using an edge-compatible driver + +When deploying a Cloudflare Worker that uses Prisma ORM, you need to use an [edge-compatible driver](/orm/prisma-client/deployment/edge/overview#edge-compatibility-of-database-drivers) and its respective [driver adapter](/orm/overview/databases/database-drivers#driver-adapters) for Prisma ORM. + +The edge-compatible drivers for Cloudflare Workers and Pages are: + +- [Neon Serverless](https://neon.tech/docs/serverless/serverless-driver) uses HTTP to access the database +- [PlanetScale Serverless](https://planetscale.com/docs/tutorials/planetscale-serverless-driver) uses HTTP to access the database +- [`node-postgres`](https://node-postgres.com/) (`pg`) uses Cloudflare's `connect()` (TCP) to access the database +- [`@libsql/client`](https://github.com/tursodatabase/libsql-client-ts) is used to access Turso databases + +There's [also work being done](https://github.com/sidorares/node-mysql2/pull/2289) on the `node-mysql2` driver which will enable access to traditional MySQL databases from Cloudflare Workers and Pages in the future as well. + +> **Note**: [Prisma Accelerate](/accelerate) enables you to access _any_ database from _any_ edge function provider. No edge-compatible driver is necessary. + +### Setting your database connection URL as an environment variable + +First, ensure that the `DATABASE_URL` is set as the `url` of the `datasource` in your Prisma schema: + +```prisma +datasource db { + provider = "postgresql" // this might also be `mysql` or another value depending on your database + url = env("DATABASE_URL") +} +``` + +#### Development + +When using your Worker in **development**, you can configure your database connection via the [`.dev.vars` file](https://developers.cloudflare.com/workers/configuration/secrets/#secrets-in-development) locally. + +Assuming you use the `DATABASE_URL` environment variable from above, you can set it inside `.dev.vars` as follows: + +```bash file=.dev.vars +DATABASE_URL="your-database-connection-string" +``` + +In the above snippet, `your-database-connection-string` is a placeholder that you need to replace with the value of your own connection string, for example: + +```bash file=.dev.vars +DATABASE_URL="postgresql://admin:mypassword42@somehost.aws.com:5432/mydb" +``` + +Note that the `.dev.vars` file is not compatible with `.env` files which are typically used by Prisma ORM. + +This means that you need to make sure that Prisma ORM gets access to the environment variable when needed, e.g. when running a Prisma CLI command like `prisma migrate dev`. + +There are several options for achieving this: + +- Run your Prisma CLI commands using [`dotenv`](https://www.npmjs.com/package/dotenv-cli) to specify from where the CLI should read the environment variable, for example: + ```terminal + dotenv -e .dev.vars -- npx prisma migrate dev + ``` +- Create a script in `package.json` that reads `.dev.vars` via [`dotenv`](https://www.npmjs.com/package/dotenv-cli). You can then execute `prisma` commands as follows: `npm run env -- npx prisma migrate dev`. Here's a reference for the script: + ```js file=package.json + "scripts": { "env": "dotenv -e .dev.vars" } + ``` +- Duplicate the `DATABASE_URL` and any other relevant env vars into a new file called `.env` which can then be used by Prisma ORM. + +> **Note**: If you're using an approach that requires `dotenv`, you need to have the [`dotenv-cli`](https://www.npmjs.com/package/dotenv-cli) package installed. You can do this e.g. by using this command to install the package locally in your project: `npm install -D dotenv-cli`. + +#### Production + +When deploying your Worker to **production**, you'll need to set the database connection using the `wrangler` CLI: + +```terminal +npx wrangler secret put DATABASE_URL +``` + +The command is interactive and will ask you to enter the value for the `DATABASE_URL` env var as the next step in the terminal. + +> **Note**: This command requires you to be authenticated, and will ask you to log in to your Cloudflare account in case you are not. + +### Size limits on free accounts + +Cloudflare has a [size limit of 1 MB for Workers on the free plan](https://developers.cloudflare.com/workers/platform/limits/). If your application bundle with Prisma ORM exceeds that size, we recommend upgrading to a paid Worker plan or using Prisma Accelerate to deploy your application. + +If you're running into this problem with `pg` and the `@prisma/adapter-pg` package, you can replace the `pg` with the custom [`@prisma/pg-worker`](https://github.com/prisma/prisma/tree/main/packages/pg-worker) package and use the [`@prisma/adapter-pg-worker`](https://github.com/prisma/prisma/tree/main/packages/adapter-pg-worker) adapter that belongs to it. + +`@prisma/pg-worker` is an optimized and lightweight version of `pg` that is designed to be used in a Worker. It is a drop-in replacement for `pg` and is fully compatible with Prisma ORM. + +### Deploying a Next.js app with `@cloudflare/next-on-pages` + +Cloudflare offers an option to run Next.js apps on Cloudflare Pages with [`@cloudflare/next-on-pages`](https://github.com/cloudflare/next-on-pages), see the [docs](https://developers.cloudflare.com/pages/framework-guides/deploy-a-nextjs-site) for instructions. + +Based on some testing, we found the following: + +- You can deploy using the PlanetScale Serverless Driver. +- Neon currently doesn't work because of a probable bug in `@cloudflare/next-on-pages` (see [here](https://github.com/cloudflare/next-on-pages/issues/499#issuecomment-1863613990) and [here](https://github.com/cloudflare/workerd/issues/1513)). +- Traditional PostgreSQL deployments using `pg` don't work because `pg` itself currently does not work on `@cloudflare/next-on-pages` (see [here](https://github.com/cloudflare/next-on-pages/issues/605)). + +Feel free to reach out to us on [Discord](https://pris.ly/discord) if you find that anything has changed about this. + +### Set `PRISMA_CLIENT_FORCE_WASM=1` when running locally with `node` + +Some frameworks (e.g. [hono](https://hono.dev/)) use `node` instead of `wrangler` for running Workers locally. If you're using such a framework or are running your Worker locally with `node` for another reason, you need to set the `PRISMA_CLIENT_FORCE_WASM` environment variable: + +``` +export PRISMA_CLIENT_FORCE_WASM=1 +``` + +## Database-specific considerations & examples + +This section provides database-specific instructions for deploying a Cloudflare Worker with Prisma ORM. + +### Prerequisites + +As a prerequisite for the following section, you need to have a Cloudflare Worker running locally and the Prisma CLI installed. + +If you don't have that yet, you can run these commands: + +```terminal +npm create cloudflare@latest prisma-cloudflare-worker-example -- --type hello-world +cd prisma-cloudflare-worker-example +npm install prisma --save-dev +npx prisma init +``` + +We'll use the default `User` model for the example below: + +```prisma +model User { + id Int @id @default(autoincrement()) + email String @unique + name String? +} +``` + +### PostgreSQL (traditional) + +If you are using a traditional PostgreSQL database that's accessed via TCP and the `pg` driver, you need to: + +- use the `@prisma/adapter-pg` database adapter (via the `driverAdapters` Preview feature) +- set `node_compat = true` in `wrangler.toml` (see the [Cloudflare docs](https://developers.cloudflare.com/workers/wrangler/configuration/#add-polyfills-using-wrangler)) + +If you are running into a size issue and can't deploy your application because of that, you can use our slimmer variant of the `pg` driver package [`@prisma/pg-worker`](https://github.com/prisma/prisma/tree/main/packages/pg-worker) and the [`@prisma/adapter-pg-worker`](https://github.com/prisma/prisma/tree/main/packages/adapter-pg-worker) adapter that belongs to it. + +`@prisma/pg-worker` is an optimized and lightweight version of `pg` that is designed to be used in a Worker. It is a drop-in replacement for `pg` and is fully compatible with Prisma ORM. + +#### 1. Configure Prisma schema & database connection + +First, ensure that the database connection is configured properly. In your Prisma schema, set the `url` of the `datasource` block to the `DATABASE_URL` environment variable. You also need to enable the `driverAdapters` feature flag: + +```prisma file=schema.prisma +generator client { + provider = "prisma-client-js" + previewFeatures = ["driverAdapters"] +} + +datasource db { + provider = "postgresql" + url = env("DATABASE_URL") +} +``` + +Next, you need to set the `DATABASE_URL` environment variable to the value of your database connection string. You'll do this in a file called `.dev.vars` used by Cloudflare: + +```bash file=.dev.vars +DATABASE_URL="postgresql://admin:mypassword42@somehost.aws.com:5432/mydb" +``` + +Because the Prisma CLI by default is only compatible with `.env` files, you can adjust your `package.json` with the following script that loads the env vars from `.dev.vars`. You can then use this script to load the env vars before executing a `prisma` command. + +Add this script to your `package.json`: + +```js file=package.json highlight=5;add +{ + // ... + "scripts": { + // .... + "env": "dotenv -e .dev.vars" + }, + // ... +} +``` + +Now you can execute Prisma CLI commands as follows while ensuring that the command has access to the env vars in `.dev.vars`: + +```terminal +npm run env -- npx prisma +``` + +#### 2. Install dependencies + +Next, install the required packages: + +```terminal +npm install @prisma/adapter-pg +npm install pg +npm install @types/pg --save-dev # if you're using TypeScript +``` + +#### 3. Set `node_compat = true` in `wrangler.toml` + +In your `wrangler.toml` file, add the following line: + +```toml file=wrangler.toml +node_compat = true +``` + +> **Note**: For Cloudflare Pages, using `node_compat` is not officially supported. If you want to use `pg` in Cloudflare Pages, you can find a workaround [here](https://github.com/cloudflare/workers-sdk/pull/2541#issuecomment-1954209855). + +#### 4. Migrate your database schema (if applicable) + +If you ran `npx prisma init` above, you need to migrate your database schema to create the `User` table that's defined in your Prisma schema (if you already have all the tables you need in your database, you can skip this step): + +```terminal +npm run env -- npx prisma migrate dev --name init +``` + +#### 5. Use Prisma Client in your Worker to send a query to the database + +Here is a sample code snippet that you can use to instantiate `PrismaClient` and send a query to your database: + +```ts +import { PrismaClient } from '@prisma/client' +import { PrismaPg } from '@prisma/adapter-pg' +import { Pool } from 'pg' + +export default { + async fetch(request, env, ctx) { + const pool = new Pool({ connectionString: env.DATABASE_URL }) + const adapter = new PrismaPg(pool) + const prisma = new PrismaClient({ adapter }) + + const users = await prisma.user.findMany() + const result = JSON.stringify(users) + return new Response(result) + }, +} +``` + +#### 6. Run the Worker locally + +To run the Worker locally, you can run the `wrangler dev` command: + +```terminal +npx wrangler dev +``` + +#### 7. Set the `DATABASE_URL` environment variable and deploy the Worker + +To deploy the Worker, you first need to the `DATABASE_URL` environment variable [via the `wrangler` CLI](https://developers.cloudflare.com/workers/configuration/secrets/#secrets-on-deployed-workers): + +```terminal +npx wrangler secret put DATABASE_URL +``` + +The command is interactive and will ask you to enter the value for the `DATABASE_URL` env var as the next step in the terminal. + +> **Note**: This command requires you to be authenticated, and will ask you to log in to your Cloudflare account in case you are not. + +Then you can go ahead then deploy the Worker: + +```terminal +npx wrangler deploy +``` + +The command will output the URL where you can access the deployed Worker. + +### PlanetScale + +If you are using a PlanetScale database, you need to: + +- use the `@prisma/adapter-planetscale` database adapter (via the `driverAdapters` Preview feature) +- manually remove the conflicting `cache` field ([learn more]()): + + ```ts + export default { + async fetch(request, env, ctx) { + const client = new Client({ + url: env.DATABASE_URL, + // see https://github.com/cloudflare/workerd/issues/698 + fetch(url, init) { + delete init['cache'] + return fetch(url, init) + }, + }) + const adapter = new PrismaPlanetScale(client) + const prisma = new PrismaClient({ adapter }) + + // ... + }, + } + ``` + +#### 1. Configure Prisma schema & database connection + +First, ensure that the database connection is configured properly. In your Prisma schema, set the `url` of the `datasource` block to the `DATABASE_URL` environment variable. You also need to enable the `driverAdapters` feature flag: + +```prisma file=schema.prisma +generator client { + provider = "prisma-client-js" + previewFeatures = ["driverAdapters"] +} + +datasource db { + provider = "mysql" + url = env("DATABASE_URL") + relationMode = "prisma" // required for PlanetScale (as by default foreign keys are disabled) +} +``` + +Next, you need to set the `DATABASE_URL` environment variable to the value of your database connection string. You'll do this in a file called `.dev.vars` used by Cloudflare: + +```bash file=.dev.vars +DATABASE_URL="mysql://32qxa2r7hfl3102wrccj:password@us-east.connect.psdb.cloud/demo-cf-worker-ps?sslaccept=strict" +``` + +Because the Prisma CLI by default is only compatible with `.env` files, you can adjust your `package.json` with the following script that loads the env vars from `.dev.vars`. You can then use this script to load the env vars before executing a `prisma` command. + +Add this script to your `package.json`: + +```js file=package.json highlight=5;add +{ + // ... + "scripts": { + // .... + "env": "dotenv -e .dev.vars" + }, + // ... +} +``` + +Now you can execute Prisma CLI commands as follows while ensuring that the command has access to the env vars in `.dev.vars`: + +```terminal +npm run env -- npx prisma +``` + +#### 2. Install dependencies + +Next, install the required packages: + +```terminal +npm install @prisma/adapter-planetscale +npm install @planetscale/database +``` + +#### 3. Migrate your database schema (if applicable) + +If you ran `npx prisma init` above, you need to migrate your database schema to create the `User` table that's defined in your Prisma schema (if you already have all the tables you need in your database, you can skip this step): + +```terminal +npm run env -- npx prisma db push +``` + +#### 4. Use Prisma Client in your Worker to send a query to the database + +Here is a sample code snippet that you can use to instantiate `PrismaClient` and send a query to your database: + +```ts +import { PrismaClient } from '@prisma/client' +import { PrismaPlanetScale } from '@prisma/adapter-planetscale' +import { Client } from '@planetscale/database' + +export default { + async fetch(request, env, ctx) { + const client = new Client({ + url: env.DATABASE_URL, + // see https://github.com/cloudflare/workerd/issues/698 + fetch(url, init) { + delete init['cache'] + return fetch(url, init) + }, + }) + const adapter = new PrismaPlanetScale(client) + const prisma = new PrismaClient({ adapter }) + + const users = await prisma.user.findMany() + const result = JSON.stringify(users) + return new Response(result) + }, +} +``` + +#### 6. Run the Worker locally + +To run the Worker locally, you can run the `wrangler dev` command: + +```terminal +npx wrangler dev +``` + +#### 7. Set the `DATABASE_URL` environment variable and deploy the Worker + +To deploy the Worker, you first need to the `DATABASE_URL` environment variable [via the `wrangler` CLI](https://developers.cloudflare.com/workers/configuration/secrets/#secrets-on-deployed-workers): + +```terminal +npx wrangler secret put DATABASE_URL +``` + +The command is interactive and will ask you to enter the value for the `DATABASE_URL` env var as the next step in the terminal. + +> **Note**: This command requires you to be authenticated, and will ask you to log in to your Cloudflare account in case you are not. + +Then you can go ahead then deploy the Worker: + +```terminal +npx wrangler deploy +``` + +The command will output the URL where you can access the deployed Worker. + +### Neon + +If you are using a Neon database, you need to: + +- use the `@prisma/adapter-neon` database adapter (via the `driverAdapters` Preview feature) + +#### 1. Configure Prisma schema & database connection + +First, ensure that the database connection is configured properly. In your Prisma schema, set the `url` of the `datasource` block to the `DATABASE_URL` environment variable. You also need to enable the `driverAdapters` feature flag: + +```prisma file=schema.prisma +generator client { + provider = "prisma-client-js" + previewFeatures = ["driverAdapters"] +} + +datasource db { + provider = "postgresql" + url = env("DATABASE_URL") +} +``` + +Next, you need to set the `DATABASE_URL` environment variable to the value of your database connection string. You'll do this in a file called `.dev.vars` used by Cloudflare: + +```bash file=.dev.vars +DATABASE_URL="postgresql://janedoe:password@ep-nameless-pond-a23b1mdz.eu-central-1.aws.neon.tech/neondb?sslmode=require" +``` + +Because the Prisma CLI by default is only compatible with `.env` files, you can adjust your `package.json` with the following script that loads the env vars from `.dev.vars`. You can then use this script to load the env vars before executing a `prisma` command. + +Add this script to your `package.json`: + +```js file=package.json highlight=5;add +{ + // ... + "scripts": { + // .... + "env": "dotenv -e .dev.vars" + }, + // ... +} +``` + +Now you can execute Prisma CLI commands as follows while ensuring that the command has access to the env vars in `.dev.vars`: + +```terminal +npm run env -- npx prisma +``` + +#### 2. Install dependencies + +Next, install the required packages: + +```terminal +npm install @prisma/adapter-neon +npm install @neondatabase/serverless +``` + +#### 3. Migrate your database schema (if applicable) + +If you ran `npx prisma init` above, you need to migrate your database schema to create the `User` table that's defined in your Prisma schema (if you already have all the tables you need in your database, you can skip this step): + +```terminal +npm run env -- npx prisma migrate dev --name init +``` + +#### 5. Use Prisma Client in your Worker to send a query to the database + +Here is a sample code snippet that you can use to instantiate `PrismaClient` and send a query to your database: + +```ts +import { PrismaClient } from '@prisma/client' +import { PrismaNeon } from '@prisma/adapter-neon' +import { Pool } from '@neondatabase/serverless' + +export default { + async fetch(request, env, ctx) { + const neon = new Pool({ connectionString: env.DATABASE_URL }) + const adapter = new PrismaNeon(neon) + const prisma = new PrismaClient({ adapter }) + + const users = await prisma.user.findMany() + const result = JSON.stringify(users) + return new Response(result) + }, +} +``` + +#### 6. Run the Worker locally + +To run the Worker locally, you can run the `wrangler dev` command: + +```terminal +npx wrangler dev +``` + +#### 7. Set the `DATABASE_URL` environment variable and deploy the Worker + +To deploy the Worker, you first need to the `DATABASE_URL` environment variable [via the `wrangler` CLI](https://developers.cloudflare.com/workers/configuration/secrets/#secrets-on-deployed-workers): + +```terminal +npx wrangler secret put DATABASE_URL +``` + +The command is interactive and will ask you to enter the value for the `DATABASE_URL` env var as the next step in the terminal. + +> **Note**: This command requires you to be authenticated, and will ask you to log in to your Cloudflare account in case you are not. + +Then you can go ahead then deploy the Worker: + +```terminal +npx wrangler deploy +``` + +The command will output the URL where you can access the deployed Worker. + +### D1 + +[Coming soon](https://github.com/prisma/prisma/issues/13310). diff --git a/content/200-orm/200-prisma-client/500-deployment/301-edge/485-deploy-to-vercel.mdx b/content/200-orm/200-prisma-client/500-deployment/301-edge/485-deploy-to-vercel.mdx new file mode 100644 index 0000000000..1692e47509 --- /dev/null +++ b/content/200-orm/200-prisma-client/500-deployment/301-edge/485-deploy-to-vercel.mdx @@ -0,0 +1,468 @@ +--- +title: 'Deploy to Vercel Edge Functions & Middleware' +sidebar_label: 'Deploy to Vercel' +metaTitle: 'Deploy to Vercel Edge Functions & Middleware' +metaDescription: 'Learn the things you need to know in order to deploy an Edge function that uses Prisma Client for talking to a database.' +tocDepth: 3 +sidebar_class_name: preview-badge +--- + + + +This page covers everything you need to know to deploy an app that uses Prisma Client for talking to a database in [Vercel Edge Middleware](https://vercel.com/docs/functions/edge-middleware) or a [Vercel Function](https://vercel.com/docs/functions) deployed to the [Vercel Edge Runtime](https://vercel.com/docs/functions/runtimes/edge-runtime). + +To deploy a Vercel Function to the Vercel Edge Runtime, you can set `export const runtime = 'edge'` outside the request handler of the Vercel Function. + + + +## General considerations when deploying to Vercel Edge Functions & Edge Middleware + +### Using an edge-compatible driver + +Vercel's Edge Runtime currently only supports a limited set of database drivers: + +- [Neon Serverless](https://neon.tech/docs/serverless/serverless-driver) uses HTTP to access the database (also compatible with [Vercel Postgres](https://vercel.com/docs/storage/vercel-postgres)) +- [PlanetScale Serverless](https://planetscale.com/docs/tutorials/planetscale-serverless-driver) uses HTTP to access the database +- [`@libsql/client`](https://github.com/tursodatabase/libsql-client-ts) is used to access Turso databases + +Note that [`node-postgres`](https://node-postgres.com/) (`pg`) is currently _not_ supported on Vercel Edge Functions. + +When deploying a Vercel Edge Function that uses Prisma ORM, you need to use one of these [edge-compatible drivers](/orm/prisma-client/deployment/edge/overview#edge-compatibility-of-database-drivers) and its respective [driver adapter](/orm/overview/databases/database-drivers#driver-adapters) for Prisma ORM. + +> **Note**: [Prisma Accelerate](/accelerate) enables you to access _any_ database from _any_ edge function provider. No edge-compatible driver is necessary. + +### Setting your database connection URL as an environment variable + +First, ensure that the `DATABASE_URL` is set as the `url` of the `datasource` in your Prisma schema: + +```prisma +datasource db { + provider = "postgresql" // this might also be `mysql` or another value depending on your database + url = env("DATABASE_URL") +} +``` + +#### Development + +When in **development**, you can configure your database connection via the `DATABASE_URL` environment variable (e.g. [using `.env` files](/orm/more/development-environment/environment-variables/env-files)). + +#### Production + +When deploying your Edge Function to **production**, you'll need to set the database connection using the `vercel` CLI: + +```terminal +npx vercel env add DATABASE_URL +``` + +This command is interactive and will ask you to select environments and provide the value for the `DATABASE_URL` in subsequent steps. + +Alternatively, you can configure the environment variable [via the UI](https://vercel.com/docs/projects/environment-variables#declare-an-environment-variable) of your project in the Vercel Dashboard. + +### Generate Prisma Client in `postinstall` hook + +In your `package.json`, you should add a `"postinstall"` section as follows: + +```js file=package.json +{ + // ..., + "postinstall: "prisma generate" +} +``` + +### Size limits on free accounts + +Vercel has a [size limit of 1 MB on free accounts](https://vercel.com/docs/functions/limitations). If your application bundle with Prisma ORM exceeds that size, we recommend upgrading to a paid account or using Prisma Accelerate to deploy your application. + +## Database-specific considerations & examples + +This section provides database-specific instructions for deploying a Vercel Edge Functions with Prisma ORM. + +### Prerequisites + +As a prerequisite for the following section, you need to have a Vercel Edge Function (which typically comes in the form of a Next.js API route) running locally and the Prisma and Vercel CLIs installed. + +If you don't have that yet, you can run these commands to set up a Next.js app from scratch (following the instructions of the [Vercel Edge Quickstart](https://vercel.com/docs/functions/edge-functions/quickstart)): + +```terminal +npm install -g vercel +npx create-next-app@latest +npm install prisma --save-dev +npx prisma init +``` + +We'll use the default `User` model for the example below: + +```prisma +model User { + id Int @id @default(autoincrement()) + email String @unique + name String? +} +``` + +### Vercel Postgres + +If you are using Vercel Postgres, you need to: + +- use the `@prisma/adapter-neon` database adapter (via the `driverAdapters` Preview feature) because Vercel Postgres uses [Neon](https://neon.tech/) under the hood +- be aware that Vercel by default calls the environment variable for the database connection string `POSTGRES_PRISMA_URL` while the default name used in the Prisma docs is typically `DATABASE_URL`; using Vercel's naming, you need to set the following fields on your `datasource` block: + ```prisma + datasource db { + provider = "postgresql" + url = env("POSTGRES_PRISMA_URL") // uses connection pooling + directUrl = env("POSTGRES_URL_NON_POOLING") // uses a direct connection + } + ``` + +#### 1. Configure Prisma schema & database connection + +First, ensure that the database connection is configured properly. In your Prisma schema, set the `url` of the `datasource` block to the `POSTGRES_PRISMA_URL` and the `directUrl` to the `POSTGRES_URL_NON_POOLING` environment variable. You also need to enable the `driverAdapters` feature flag: + +```prisma file=schema.prisma +generator client { + provider = "prisma-client-js" + previewFeatures = ["driverAdapters"] +} + +datasource db { + provider = "postgresql" + url = env("POSTGRES_PRISMA_URL") // uses connection pooling + directUrl = env("POSTGRES_URL_NON_POOLING") // uses a direct connection +} +``` + +Next, you need to set the `POSTGRES_PRISMA_URL` and `POSTGRES_URL_NON_POOLING` environment variable to the values of your database connection. + +If you ran `npx prisma init`, you can use the `.env` file that was created by this command to set these: + +```bash file=.env +POSTGRES_PRISMA_URL="postgres://user:password@host-pooler.region.postgres.vercel-storage.com:5432/name?pgbouncer=true&connect_timeout=15" +POSTGRES_URL_NON_POOLING="postgres://user:password@host.region.postgres.vercel-storage.com:5432/name" +``` + +#### 2. Install dependencies + +Next, install the required packages: + +```terminal +npm install @prisma/adapter-neon +npm install @neondatabase/serverless +``` + +#### 3. Configure `postinstall` hook + +Next, add a new key to the `scripts` section in your `package.json`: + +```js file=package.json highlight=5;add +{ + // ... + "scripts": { + // ... + "postinstall": "prisma generate" + } +} +``` + +#### 4. Migrate your database schema (if applicable) + +If you ran `npx prisma init` above, you need to migrate your database schema to create the `User` table that's defined in your Prisma schema (if you already have all the tables you need in your database, you can skip this step): + +```terminal +npx prisma migrate dev --name init +``` + +#### 5. Use Prisma Client in your Vercel Edge Function to send a query to the database + +If you created the project from scratch, you can create a new edge function as follows. + +First, create a new API route, e.g. by using these commands: + +```terminal +mkdir src/app/api +mkdir src/app/api/edge +touch src/app/api/edge/route.ts +``` + +Here is a sample code snippet that you can use to instantiate `PrismaClient` and send a query to your database in the new `app/api/edge/route.ts` file you just created: + +```ts file=app/api/edge/route.ts +import { NextResponse } from 'next/server' +import { PrismaClient } from '@prisma/client' +import { PrismaNeon } from '@prisma/adapter-neon' +import { Pool } from '@neondatabase/serverless' + +export const runtime = 'edge' + +export async function GET(request: Request) { + const neon = new Pool({ connectionString: process.env.POSTGRES_PRISMA_URL }) + const adapter = new PrismaNeon(neon) + const prisma = new PrismaClient({ adapter }) + + const users = await prisma.user.findMany() + + return NextResponse.json(users, { status: 200 }) +} +``` + +#### 6. Run the Edge Function locally + +Run the app with the following command: + +```terminal +npm run dev +``` + +You can now access the Edge Function via this URL: [`http://localhost:3000/api/edge`](http://localhost:3000/api/edge). + +#### 7. Set the `POSTGRES_PRISMA_URL` environment variable and deploy the Edge Function + +Run the following command to deploy your project with Vercel: + +```terminal +npx vercel deploy +``` + +Note that once the project was created on Vercel, you will need to set the `POSTGRES_PRISMA_URL` environment variable (and if this was your first deploy, it likely failed). You can do this either via the Vercel UI or by running the following command: + +``` +npx vercel env add POSTGRES_PRISMA_URL +``` + +At this point, you can get the URL of the deployed application from the Vercel Dashboard and access the edge function via the `/api/edge` route. + +### PlanetScale + +If you are using a PlanetScale database, you need to: + +- use the `@prisma/adapter-planetscale` database adapter (via the `driverAdapters` Preview feature) + +#### 1. Configure Prisma schema & database connection + +First, ensure that the database connection is configured properly. In your Prisma schema, set the `url` of the `datasource` block to the `DATABASE_URL` environment variable. You also need to enable the `driverAdapters` feature flag: + +```prisma file=schema.prisma +generator client { + provider = "prisma-client-js" + previewFeatures = ["driverAdapters"] +} + +datasource db { + provider = "mysql" + url = env("DATABASE_URL") + relationMode = "prisma" // required for PlanetScale (as by default foreign keys are disabled) +} +``` + +Next, you need to set the `DATABASE_URL` environment variable in your `.env` file that's used both by Prisma and Next.js to read your env vars: + +```bash file=.env +DATABASE_URL="mysql://32qxa2r7hfl3102wrccj:password@us-east.connect.psdb.cloud/demo-cf-worker-ps?sslaccept=strict" +``` + +#### 2. Install dependencies + +Next, install the required packages: + +```terminal +npm install @prisma/adapter-planetscale +npm install @planetscale/database +``` + +#### 3. Configure `postinstall` hook + +Next, add a new key to the `scripts` section in your `package.json`: + +```js file=package.json highlight=5;add +{ + // ... + "scripts": { + // ... + "postinstall": "prisma generate" + } +} +``` + +#### 4. Migrate your database schema (if applicable) + +If you ran `npx prisma init` above, you need to migrate your database schema to create the `User` table that's defined in your Prisma schema (if you already have all the tables you need in your database, you can skip this step): + +```terminal +npx prisma db push +``` + +#### 5. Use Prisma Client in an Edge Function to send a query to the database + +If you created the project from scratch, you can create a new edge function as follows. + +First, create a new API route, e.g. by using these commands: + +```terminal +mkdir src/app/api +mkdir src/app/api/edge +touch src/app/api/edge/route.ts +``` + +Here is a sample code snippet that you can use to instantiate `PrismaClient` and send a query to your database in the new `app/api/edge/route.ts` file you just created: + +```ts file=app/api/edge/route.ts +import { NextResponse } from 'next/server' +import { PrismaClient } from '@prisma/client' +import { PrismaPlanetScale } from '@prisma/adapter-planetscale' +import { Client } from '@planetscale/database' + +export const runtime = 'edge' + +export async function GET(request: Request) { + const client = new Client({ url: process.env.DATABASE_URL }) + const adapter = new PrismaPlanetScale(client) + const prisma = new PrismaClient({ adapter }) + + const users = await prisma.user.findMany() + + return NextResponse.json(users, { status: 200 }) +} +``` + +#### 6. Run the Edge Function locally + +Run the app with the following command: + +```terminal +npm run dev +``` + +You can now access the Edge Function via this URL: [`http://localhost:3000/api/edge`](http://localhost:3000/api/edge). + +#### 7. Set the `DATABASE_URL` environment variable and deploy the Edge Function + +Run the following command to deploy your project with Vercel: + +```terminal +npx vercel deploy +``` + +Note that once the project was created on Vercel, you will need to set the `DATABASE_URL` environment variable (and if this was your first deploy, it likely failed). You can do this either via the Vercel UI or by running the following command: + +``` +npx vercel env add DATABASE_URL +``` + +At this point, you can get the URL of the deployed application from the Vercel Dashboard and access the edge function via the `/api/edge` route. + +### Neon + +If you are using a Neon database, you need to: + +- use the `@prisma/adapter-neon` database adapter (via the `driverAdapters` Preview feature) + +#### 1. Configure Prisma schema & database connection + +First, ensure that the database connection is configured properly. In your Prisma schema, set the `url` of the `datasource` block to the `DATABASE_URL` environment variable. You also need to enable the `driverAdapters` feature flag: + +```prisma file=schema.prisma +generator client { + provider = "prisma-client-js" + previewFeatures = ["driverAdapters"] +} + +datasource db { + provider = "postgresql" + url = env("DATABASE_URL") +} +``` + +Next, you need to set the `DATABASE_URL` environment variable in your `.env` file that's used both by Prisma and Next.js to read your env vars: + +```bash file=.env +DATABASE_URL="postgresql://janedoe:password@ep-nameless-pond-a23b1mdz.eu-central-1.aws.neon.tech/neondb?sslmode=require" +``` + +#### 2. Install dependencies + +Next, install the required packages: + +```terminal +npm install @prisma/adapter-neon +npm install @neondatabase/serverless +``` + +#### 3. Configure `postinstall` hook + +Next, add a new key to the `scripts` section in your `package.json`: + +```js file=package.json highlight=5;add +{ + // ... + "scripts": { + // ... + "postinstall": "prisma generate" + } +} +``` + +#### 4. Migrate your database schema (if applicable) + +If you ran `npx prisma init` above, you need to migrate your database schema to create the `User` table that's defined in your Prisma schema (if you already have all the tables you need in your database, you can skip this step): + +```terminal +npx prisma migrate dev --name init +``` + +#### 5. Use Prisma Client in an Edge Function to send a query to the database + +If you created the project from scratch, you can create a new edge function as follows. + +First, create a new API route, e.g. by using these commands: + +```terminal +mkdir src/app/api +mkdir src/app/api/edge +touch src/app/api/edge/route.ts +``` + +Here is a sample code snippet that you can use to instantiate `PrismaClient` and send a query to your database in the new `app/api/edge/route.ts` file you just created: + +```ts file=app/api/edge/route.ts +import { NextResponse } from 'next/server' +import { PrismaClient } from '@prisma/client' +import { PrismaNeon } from '@prisma/adapter-neon' +import { Pool } from '@neondatabase/serverless' + +export const runtime = 'edge' + +export async function GET(request: Request) { + const neon = new Pool({ connectionString: process.env.DATABASE_URL }) + const adapter = new PrismaNeon(neon) + const prisma = new PrismaClient({ adapter }) + + const users = await prisma.user.findMany() + + return NextResponse.json(users, { status: 200 }) +} +``` + +#### 6. Run the Edge Function locally + +Run the app with the following command: + +```terminal +npm run dev +``` + +You can now access the Edge Function via this URL: [`http://localhost:3000/api/edge`](http://localhost:3000/api/edge). + +#### 7. Set the `DATABASE_URL` environment variable and deploy the Edge Function + +Run the following command to deploy your project with Vercel: + +```terminal +npx vercel deploy +``` + +Note that once the project was created on Vercel, you will need to set the `DATABASE_URL` environment variable (and if this was your first deploy, it likely failed). You can do this either via the Vercel UI or by running the following command: + +``` +npx vercel env add DATABASE_URL +``` + +At this point, you can get the URL of the deployed application from the Vercel Dashboard and access the edge function via the `/api/edge` route. diff --git a/content/200-orm/200-prisma-client/500-deployment/301-edge/index.mdx b/content/200-orm/200-prisma-client/500-deployment/301-edge/index.mdx index 6eb159be3b..e1962bb1ad 100644 --- a/content/200-orm/200-prisma-client/500-deployment/301-edge/index.mdx +++ b/content/200-orm/200-prisma-client/500-deployment/301-edge/index.mdx @@ -7,10 +7,10 @@ tocDepth: 2 -If your application is deployed via an "Edge Function" offering or is deployed from a [serverless](/orm/prisma-client/deployment/serverless) offering and has a non-standard runtime, it is a edge deployed app. Common examples include [Cloudflare Workers](/orm/prisma-client/deployment/edge/deploy-to-cloudflare-workers), [Deno Deploy](/orm/prisma-client/deployment/edge/deploy-to-deno-deploy), and Vercel Edge Functions. +If your application is deployed via an "Edge Function" offering or is deployed from a [serverless](/orm/prisma-client/deployment/serverless) offering and has a non-standard runtime, it is a _edge-deployed_ app. Common examples for such offerings include [Cloudflare Workers or Pages](/orm/prisma-client/deployment/edge/deploy-to-cloudflare), [Vercel Edge Functions or Edge Middleware](/orm/prisma-client/deployment/edge/deploy-to-vercel), and [Deno Deploy](/orm/prisma-client/deployment/edge/deploy-to-deno-deploy). -## Guides for Edge Function providers +## In this section diff --git a/content/200-orm/200-prisma-client/500-deployment/210-module-bundlers.mdx b/content/200-orm/200-prisma-client/500-deployment/400-module-bundlers.mdx similarity index 72% rename from content/200-orm/200-prisma-client/500-deployment/210-module-bundlers.mdx rename to content/200-orm/200-prisma-client/500-deployment/400-module-bundlers.mdx index cc5d791f13..4fb5c843f7 100644 --- a/content/200-orm/200-prisma-client/500-deployment/210-module-bundlers.mdx +++ b/content/200-orm/200-prisma-client/500-deployment/400-module-bundlers.mdx @@ -14,8 +14,8 @@ Since Prisma Client is not only based on JavaScript code, but also relies on the To do so, you can use plugins that let you copy over static assets: -| Bundler | Plugin | -| :----------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- | -| Webpack | [`copy-webpack-plugin`](https://github.com/webpack-contrib/copy-webpack-plugin#copy-webpack-plugin) | +| Bundler | Plugin | +| :---------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- | +| Webpack | [`copy-webpack-plugin`](https://github.com/webpack-contrib/copy-webpack-plugin#copy-webpack-plugin) | | Webpack (with [Next.js monorepo](/orm/more/help-and-troubleshooting/help-articles/nextjs-prisma-client-monorepo)) | [`nextjs-monorepo-workaround-plugin`](https://www.npmjs.com/package/@prisma/nextjs-monorepo-workaround-plugin) | -| Parcel | [`parcel-plugin-static-files-copy`](https://github.com/elwin013/parcel-plugin-static-files-copy#readme) | +| Parcel | [`parcel-plugin-static-files-copy`](https://github.com/elwin013/parcel-plugin-static-files-copy#readme) | diff --git a/content/200-orm/200-prisma-client/500-deployment/650-caveats-when-deploying-to-aws-platforms.mdx b/content/200-orm/200-prisma-client/500-deployment/650-caveats-when-deploying-to-aws-platforms.mdx index b0c38df542..537c687e0f 100644 --- a/content/200-orm/200-prisma-client/500-deployment/650-caveats-when-deploying-to-aws-platforms.mdx +++ b/content/200-orm/200-prisma-client/500-deployment/650-caveats-when-deploying-to-aws-platforms.mdx @@ -53,13 +53,15 @@ The [deployment package (.zip) size limit for lambdas is 50MB](https://docs.aws. Prisma CLI downloads additional engine binaries that are **not required** in production. You can delete the following files and folders: 1. The entire `node_modules/@prisma/engines` folder (refer to the [sample bash script](https://github.com/prisma/ecosystem-tests/blob/13e74dc47eababa5d3c8f488b73fe7fc8bffead7/platforms-serverless/lambda/run.sh#L16) used by the Prisma end-to-end tests) -2. The **local engine file** for your development platform from the `node_modules/.prisma/client` folder. For example, your schema might define the following `binaryTargets` if you develop on Debian (`native`) but deploy to AWS Lambda (`rhel-openssl-1.0.x`): +2. The **local engine file** for your development platform from the `node_modules/.prisma/client` folder. For example, your schema might define the following `binaryTargets` if you develop on Debian (`native`) but deploy to AWS Lambda (`rhel-openssl-3.0.x`): ```prisma - binaryTargets = ["native", "rhel-openssl-1.0.x"] + binaryTargets = ["native", "rhel-openssl-3.0.x"] ``` In this scenario: - - Keep `node_modules/.prisma/client/query-engine-rhel-openssl-1.0.x`, which is the engine file used by AWS Lambda + - Keep `node_modules/.prisma/client/query-engine-rhel-openssl-3.0.x`, which is the engine file used by AWS Lambda - Delete `node_modules/.prisma/client/query-engine-debian-openssl-1.1.x`, which is only required locally + + > **Note**: When using Node.js 18 or earlier, the correct `binaryTarget` for AWS Lambda is `rhel-openssl-1.0.x`. `rhel-openssl-3.0.x` is the correct `binaryTarget` for Node.js versions greater than 18. 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 c2603ae4c9..65351c6f95 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 @@ -123,7 +123,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/300-prisma-migrate/200-understanding-prisma-migrate/600-legacy-migrate.mdx b/content/200-orm/300-prisma-migrate/200-understanding-prisma-migrate/600-legacy-migrate.mdx index 7d5f55e4dc..7d0c02c04f 100644 --- a/content/200-orm/300-prisma-migrate/200-understanding-prisma-migrate/600-legacy-migrate.mdx +++ b/content/200-orm/300-prisma-migrate/200-understanding-prisma-migrate/600-legacy-migrate.mdx @@ -25,7 +25,7 @@ If you want to prototype or iterate on a schema design in a development environm Legacy Prisma Migrate is a _declarative_ migration system, as opposed to SQL which can be considered _imperative_: - **SQL (imperative)**: Provide the individual _steps_ to get from the current schema to the desired schema. -- **legacy Prisma Migrate (declarative)**: Define the desired schema as a [Prisma data model](/orm/prisma-schema/data-model/models) (legacy Prisma Migrate takes care of generating the necessary _steps_). +- **legacy Prisma Migrate (declarative)**: Define the desired schema as a [Prisma schema data model](/orm/prisma-schema/data-model/models) (legacy Prisma Migrate takes care of generating the necessary _steps_). Here's a quick comparison. Assume you have the following scenario: @@ -73,7 +73,7 @@ ADD COLUMN published BOOLEAN DEFAULT false; #### legacy Prisma Migrate -With legacy Prisma Migrate, you write the desired database schema in the form of a [Prisma data model](/orm/prisma-schema/data-model/models) inside your [Prisma schema file](/orm/prisma-schema). To map the data model to your database schema, you then have to run these two commands: +With legacy Prisma Migrate, you write the desired database schema in the form of a [Prisma schema data model](/orm/prisma-schema/data-model/models) inside your [Prisma schema file](/orm/prisma-schema). To map the data model to your database schema, you then have to run these two commands: ```terminal prisma migrate save --experimental @@ -222,7 +222,7 @@ The `_Migration` table additionally stores information about each migration that With **legacy Prisma Migrate**, the workflow looks slightly different: -1. Manually adjust your [Prisma data model](/orm/prisma-schema/data-model/models) +1. Manually adjust your [Prisma schema data model](/orm/prisma-schema/data-model/models) 1. Migrate your database using the `legacy Prisma Migrate` CLI commands 1. (Re-)generate Prisma Client 1. Use Prisma Client in your application code to access your database 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 1eab15dc13..b0ba841f74 100644 --- a/content/200-orm/500-reference/050-prisma-client-reference.mdx +++ b/content/200-orm/500-reference/050-prisma-client-reference.mdx @@ -479,7 +479,7 @@ Allows to set [transaction options](/orm/prisma-client/queries/transactions#tran #### Remarks -- The transaction levels can be overriden on a per-transaction level. +- The transaction levels can be overridden on a per-transaction level. #### Options @@ -1893,7 +1893,7 @@ const usersWithCount = await prisma.user.findMany({ `relationLoadStrategy` specifies how a relation should be loaded from the database. It has two possible values: -- `join` (default): Uses a database-level `LATERAL JOIN` and fetches all data with a single query to the database. +- `join` (default): Uses a database-level `LATERAL JOIN` (PostgreSQL) or correlated subqueries (MySQL) and fetches all data with a single query to the database. - `query`: Sends multiple queries to the database (one per table) and joins them on the application level. > **Note**: Once `relationLoadStrategy` moves from [Preview](/orm/more/releases#preview) into [General Availability](/orm/more/releases/#generally-available-ga), `join` will universally become the default for all relation queries. @@ -1909,7 +1909,7 @@ generator client { } ``` -After adding this flag, you need to run `prisma generate` again to re-generate Prisma Client. Also note that this feature is currently only available on PostgreSQL and CockroachDB, support for other DBs is coming soon. +After adding this flag, you need to run `prisma generate` again to re-generate Prisma Client. This feature is currently available on PostgreSQL, CockroachDB and MySQL. #### Remarks @@ -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/100-prisma-schema-reference.mdx b/content/200-orm/500-reference/100-prisma-schema-reference.mdx index eed0a4502c..28a5187a1e 100644 --- a/content/200-orm/500-reference/100-prisma-schema-reference.mdx +++ b/content/200-orm/500-reference/100-prisma-schema-reference.mdx @@ -17,14 +17,14 @@ Defines a [data source](/orm/prisma-schema/overview/data-sources) in the Prisma A `datasource` block accepts the following fields: -| Name | Required | Type | Description | -| ------------------- | -------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider` | **Yes** | String (`postgresql`, `mysql`, `sqlite`, `sqlserver`, `mongodb`, `cockroachdb`) | Describes which data source connectors to use. | -| `url` | **Yes** | String (URL) | Connection URL including authentication info. Most connectors use [the syntax provided by the database](/orm/reference/connection-urls#format). | -| `shadowDatabaseUrl` | No | String (URL) | Connection URL to the shadow database used by Prisma Migrate. Allows you to use a cloud-hosted database as the shadow database. | +| Name | Required | Type | Description | +| ------------------- | -------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider` | **Yes** | String (`postgresql`, `mysql`, `sqlite`, `sqlserver`, `mongodb`, `cockroachdb`) | Describes which data source connectors to use. | +| `url` | **Yes** | String (URL) | Connection URL including authentication info. Most connectors use [the syntax provided by the database](/orm/reference/connection-urls#format). | +| `shadowDatabaseUrl` | No | String (URL) | Connection URL to the shadow database used by Prisma Migrate. Allows you to use a cloud-hosted database as the shadow database. | | `directUrl` | No | String (URL) | Connection URL for direct connection to the database.

If you use a connection pooler URL in the `url` argument (for example, if you use [Prisma Accelerate](/accelerate) or pgBouncer), Prisma CLI commands that require a direct connection to the database use the URL in the `directUrl` argument.

The `directUrl` property is supported by Prisma Studio from version 5.1.0 upwards. | -| `relationMode` | No | String (`foreignKeys`, `prisma`) | Sets whether [referential integrity](/orm/prisma-schema/data-model/relations/relation-mode) is enforced by foreign keys in the database or emulated in the Prisma Client.

In preview in versions 3.1.1 and later. The field is named `relationMode` in versions 4.5.0 and later, and was previously named `referentialIntegrity`. | -| `extensions` | No | List of strings (PostgreSQL extension names) | Allows you to [represent PostgreSQL extensions in your schema](/orm/prisma-schema/postgresql-extensions#how-to-represent-postgresql-extensions-in-your-prisma-schema). Available in preview for PostgreSQL only in Prisma ORM versions 4.5.0 and later. | +| `relationMode` | No | String (`foreignKeys`, `prisma`) | Sets whether [referential integrity](/orm/prisma-schema/data-model/relations/relation-mode) is enforced by foreign keys in the database or emulated in the Prisma Client.

In preview in versions 3.1.1 and later. The field is named `relationMode` in versions 4.5.0 and later, and was previously named `referentialIntegrity`. | +| `extensions` | No | List of strings (PostgreSQL extension names) | Allows you to [represent PostgreSQL extensions in your schema](/orm/prisma-schema/postgresql-extensions#how-to-represent-postgresql-extensions-in-your-prisma-schema). Available in preview for PostgreSQL only in Prisma ORM versions 4.5.0 and later. | The following providers are available: @@ -2771,7 +2771,7 @@ model Post { ### `@ignore` -Add `@ignore` to a field that you want to exclude from Prisma Client (for example, a field that you do not want Prisma users to update). Ignored fields are excluded from the generated Prisma Client. The model's `create` method is disabled when doing this for _required_ fields with no `@default` (because the database cannot create an entry without that data). +Add `@ignore` to a field that you want to exclude from Prisma Client (for example, a field that you do not want Prisma Client users to update). Ignored fields are excluded from the generated Prisma Client. The model's `create` method is disabled when doing this for _required_ fields with no `@default` (because the database cannot create an entry without that data). #### Remarks @@ -3165,7 +3165,7 @@ circle Unsupported("circle")? @default(dbgenerated("'<(10,4),11>'::circle" ##### Override default value behavior for supported types -You can also use `dbgenerated()` to set the default value for supported types. For example, in PostgreSQL you can generate UUIDs at the database level rather than rely on Prisma's `uuid()`: +You can also use `dbgenerated()` to set the default value for supported types. For example, in PostgreSQL you can generate UUIDs at the database level rather than rely on Prisma ORM's `uuid()`: ```prisma highlight=2;add|3;delete model User { diff --git a/content/200-orm/500-reference/200-prisma-cli-reference.mdx b/content/200-orm/500-reference/200-prisma-cli-reference.mdx index 6331d6bb3f..feab458047 100644 --- a/content/200-orm/500-reference/200-prisma-cli-reference.mdx +++ b/content/200-orm/500-reference/200-prisma-cli-reference.mdx @@ -334,12 +334,12 @@ generator client { #### Options -| Option | Required | Description | Default | -| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -| `--data-proxy` | No | The `generate` command will generate Prisma Client for use with [Prisma Accelerate](/accelerate) prior to Prisma 5.0.0. Mutually exclusive with `--accelerate` and `--no-engine`. | -| `--accelerate` | No | The `generate` command will generate Prisma Client for use with [Prisma Accelerate](/accelerate). Mutually exclusive with `--data-proxy` and `--no-engine`. Available in Prisma 5.1.0 and later. | +| Option | Required | Description | Default | +| -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| `--data-proxy` | No | The `generate` command will generate Prisma Client for use with [Prisma Accelerate](/accelerate) prior to Prisma 5.0.0. Mutually exclusive with `--accelerate` and `--no-engine`. | +| `--accelerate` | No | The `generate` command will generate Prisma Client for use with [Prisma Accelerate](/accelerate). Mutually exclusive with `--data-proxy` and `--no-engine`. Available in Prisma 5.1.0 and later. | | `--no-engine` | No | The `generate` command will generate Prisma Client without an accompanied engine for use with [Prisma Accelerate](/accelerate). Mutually exclusive with `--data-proxy` and `--accelerate`. Available in Prisma ORM 5.2.0 and later. | -| `--watch` | No | The `generate` command will continue to watch the `schema.prisma` file and re-generate Prisma Client on file changes. | +| `--watch` | No | The `generate` command will continue to watch the `schema.prisma` file and re-generate Prisma Client on file changes. | @@ -762,7 +762,7 @@ prisma db pull ```code no-copy Introspecting based on datasource defined in schema.prisma … -✔ Wrote Prisma data model into schema.prisma in 38ms +✔ Introspected 2 models and wrote them into schema.prisma in 38ms Run prisma generate to generate Prisma Client. ``` @@ -788,7 +788,7 @@ prisma db pull --schema=./alternative/schema.prisma ```code no-copy Introspecting based on datasource defined in alternative/schema.prisma … -✔ Wrote Prisma data model into alternative/schema.prisma in 60ms +✔ Introspected 2 models and wrote them into alternative/schema.prisma in 60ms Run prisma generate to generate Prisma Client. ``` @@ -1269,7 +1269,7 @@ where the `--from-...` and `--to-...` options are selected based on the type of - live databases - migration histories -- Prisma data models +- Prisma schema data models - an empty schema Both schema sources must use the same database provider. For example, a diff comparing a PostgreSQL data source with a SQLite data source is not supported. diff --git a/content/200-orm/500-reference/250-error-reference.mdx b/content/200-orm/500-reference/250-error-reference.mdx index f05300e8ca..7ab6b2b0fc 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,6 +488,45 @@ 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`. + +#### `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](/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](/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/500-reference/300-environment-variables-reference.mdx b/content/200-orm/500-reference/300-environment-variables-reference.mdx index dda26f7a69..e4fffb7ae9 100644 --- a/content/200-orm/500-reference/300-environment-variables-reference.mdx +++ b/content/200-orm/500-reference/300-environment-variables-reference.mdx @@ -270,10 +270,12 @@ The `PRISMA_FMT_BINARY` variable is used in versions [4.2.0](https://github.com/ `PRISMA_CLI_BINARY_TARGETS` can be used to specify one or more binary targets that Prisma CLI will download during installation (so it must be provided during `npm install` of Prisma CLI and does not affect runtime of Prisma CLI or Prisma Client). -Use `PRISMA_CLI_BINARY_TARGETS` if you 1) deploy to a specific platform via an upload of a local project that includes dependencies, and 2) your local environment is different from the target (e.g. AWS Lambda is `rhel-openssl-1.0.x`, and your local environment might be macOS arm64 `darwin-arm64`). Using the `PRISMA_CLI_BINARY_TARGETS` environment variable ensures that the target engine files are also downloaded. +Use `PRISMA_CLI_BINARY_TARGETS` if you 1) deploy to a specific platform via an upload of a local project that includes dependencies, and 2) your local environment is different from the target (e.g. AWS Lambda with Node.js 20+ is `rhel-openssl-3.0.x`, and your local environment might be macOS arm64 `darwin-arm64`). Using the `PRISMA_CLI_BINARY_TARGETS` environment variable ensures that the target engine files are also downloaded. ```terminal -PRISMA_CLI_BINARY_TARGETS=darwin-arm64,rhel-openssl-1.0.x npm install +PRISMA_CLI_BINARY_TARGETS=darwin-arm64,rhel-openssl-3.0.x npm install ``` This is the Prisma CLI equivalent for the [`binaryTargets` property of the `generator` block](/orm/prisma-schema/overview/generators#binary-targets), which enables you to define the same setting for Prisma Client. + +> **Note**: For Node.js versions earlier than 20, the openssl version was 1.0.x instead of 3.0.x. This is most obvious in AWS Lambda deployments, where the binary target would be `rhel-openssl-1.0.x` instead of `rhel-openssl-3.0.x`. diff --git a/content/200-orm/500-reference/350-database-features.mdx b/content/200-orm/500-reference/350-database-features.mdx index baacf0bb76..6793d027fb 100644 --- a/content/200-orm/500-reference/350-database-features.mdx +++ b/content/200-orm/500-reference/350-database-features.mdx @@ -68,7 +68,7 @@ Algorithm specified via `USING`: | SP-GiST | ✔️ | ✔️ | No | No | ✔️ | ✔️† | ✔️\* | Not yet | - \* Only available if natively supported by database. -- † Available with the PostgreSQL connector only in Prisma versions `4.0.0` and later. +- † Available with the PostgreSQL connector only in Prisma ORM versions `4.0.0` and later. ### Misc @@ -97,17 +97,17 @@ This section describes which database features exist on the NoSQL databases that The following table lists common MongoDB features and describes the level of support offered by Prisma ORM: | Feature | Supported by Prisma ORM | Notes | -| ----------------------------------------- | :-----------------: | :---------------------------------------------------------------------------------------------: | -| Embedded documents | ✔️ | | -| Transactions | ✔️ | | -| Indexes | ✔️ with caveats | Indexes can only be introspected if the field they refer to includes at least some data. | -| Autoincrementing IDs | No | | -| Compound IDs | No | MongoDB does not support composite IDs (`@@id`) | -| Generated `ObjectId` | ✔️ | See: [Defining IDs for MongoDB](/orm/prisma-schema/data-model/models#defining-ids-in-mongodb) | -| Arrays | ✔️ | | -| Enums | ✔️ | Implemented at Prisma ORM level | -| Native database types | ✔️ | See: [Field mapping reference](/orm/reference/prisma-schema-reference#model-field-scalar-types) | -| JSON support | ✔️ | Advanced `Json` field filtering is not yet supported. | -| DBrefs | No | -| Change streams | No | -| Direct access to the aggregation pipeline | No | +| ----------------------------------------- | :---------------------: | :---------------------------------------------------------------------------------------------: | +| Embedded documents | ✔️ | | +| Transactions | ✔️ | | +| Indexes | ✔️ with caveats | Indexes can only be introspected if the field they refer to includes at least some data. | +| Autoincrementing IDs | No | | +| Compound IDs | No | MongoDB does not support composite IDs (`@@id`) | +| Generated `ObjectId` | ✔️ | See: [Defining IDs for MongoDB](/orm/prisma-schema/data-model/models#defining-ids-in-mongodb) | +| Arrays | ✔️ | | +| Enums | ✔️ | Implemented at Prisma ORM level | +| Native database types | ✔️ | See: [Field mapping reference](/orm/reference/prisma-schema-reference#model-field-scalar-types) | +| JSON support | ✔️ | Advanced `Json` field filtering is not yet supported. | +| DBrefs | No | +| Change streams | No | +| Direct access to the aggregation pipeline | No | diff --git a/content/200-orm/500-reference/375-supported-databases.mdx b/content/200-orm/500-reference/375-supported-databases.mdx index 1216be448d..baaae5e1d1 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/200-orm/500-reference/500-preview-features/050-client-preview-features.mdx b/content/200-orm/500-reference/500-preview-features/050-client-preview-features.mdx index 626f019f30..ff43ab1447 100644 --- a/content/200-orm/500-reference/500-preview-features/050-client-preview-features.mdx +++ b/content/200-orm/500-reference/500-preview-features/050-client-preview-features.mdx @@ -57,36 +57,36 @@ To enable a Prisma Client Preview feature: In the list below, you can find a history of Prisma Client and Prisma schema features that were in Preview and are now in general availability. The features are sorted by the most recent version in which they were promoted to general availability. -| Feature | Released into Preview | Released into General Availability | -| -------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------: | -| `jsonProtocol` | [4.11.0](https://github.com/prisma/prisma/releases/tag/4.11.0) | [5.0.0](https://github.com/prisma/prisma/releases/tag/5.0.0) | -| [`extendedWhereUnique`](/orm/reference/prisma-client-reference#filter-on-non-unique-fields-with-userwhereuniqueinput) | [4.5.0](https://github.com/prisma/prisma/releases/tag/4.5.0) | [5.0.0](https://github.com/prisma/prisma/releases/tag/5.0.0) | -| [`fieldReference`](/orm/reference/prisma-client-reference#compare-columns-in-the-same-table) | [4.3.0](https://github.com/prisma/prisma/releases/tag/4.3.0) | [5.0.0](https://github.com/prisma/prisma/releases/tag/5.0.0) | -| [`clientExtensions`](/orm/prisma-client/client-extensions) | [4.7.0](https://github.com/prisma/prisma/releases/tag/4.7.0) | [4.16.0](https://github.com/prisma/prisma/releases/tag/4.16.0) | -| [`filteredRelationCount`](/orm/prisma-client/queries/aggregation-grouping-summarizing#filter-the-relation-count) | [4.3.0](https://github.com/prisma/prisma/releases/tag/4.3.0) | [4.16.0](https://github.com/prisma/prisma/releases/tag/4.16.0) | -| [`orderByNulls`](/orm/prisma-client/queries/filtering-and-sorting#sort-with-null-records-first-or-last) | [4.1.0](https://github.com/prisma/prisma/releases/tag/4.1.0) | [4.16.0](https://github.com/prisma/prisma/releases/tag/4.16.0) | -| [`referentialIntegrity`](/orm/prisma-schema/data-model/relations/relation-mode) | [3.1.1](https://github.com/prisma/prisma/releases/tag/3.1.1) | [4.7.0](https://github.com/prisma/prisma/releases/tag/4.7.0) | -| [`interactiveTransactions`](/orm/prisma-client/queries/transactions#interactive-transactions) | [2.29.0](https://github.com/prisma/prisma/releases/tag/2.29.0) |
  • [4.7.0](https://github.com/prisma/prisma/releases/tag/4.7.0)
  • with Prisma Accelerate [5.1.1](https://github.com/prisma/prisma/releases/tag/5.1.1)
| -| [`extendedIndexes`](/orm/prisma-schema/data-model/indexes) | [3.5.0](https://github.com/prisma/prisma/releases/tag/3.5.0) | [4.0.0](https://github.com/prisma/prisma/releases/tag/4.0.0) | -| [`filterJson`](/orm/prisma-client/special-fields-and-types/working-with-json-fields#filter-on-a-json-field) | [2.23.0](https://github.com/prisma/prisma/releases/tag/2.23.0) | [4.0.0](https://github.com/prisma/prisma/releases/tag/4.0.0) | -| [`improvedQueryRaw`](/orm/prisma-client/queries/raw-database-access/raw-queries#raw-query-type-mapping) | [3.14.0](https://github.com/prisma/prisma/releases/tag/3.14.0) | [4.0.0](https://github.com/prisma/prisma/releases/tag/4.0.0) | -| [`cockroachdb`](/orm/overview/databases/cockroachdb) |
  • [3.9.0](https://github.com/prisma/prisma/releases/tag/3.9.0)
  • migrations in CockroachDB in [3.11.0](https://github.com/prisma/prisma/releases/tag/3.11.0)
| [3.14.0](https://github.com/prisma/prisma/releases/tag/3.14.0) | -| [`mongodb`](/orm/overview/databases/mongodb) |
  • [2.27.0](https://github.com/prisma/prisma/releases/tag/2.27.0)
  • introspection of MongoDB in [3.2.0](https://github.com/prisma/prisma/releases/tag/3.2.0)
  • introspection of embedded documents in [3.4.0](https://github.com/prisma/prisma/releases/tag/3.4.0)
  • MongoDB embedded documents in [3.10.0](https://github.com/prisma/prisma/releases/tag/3.10.0)
  • introspection of embedded documents in [3.10.0](https://github.com/prisma/prisma/releases/tag/3.10.0)
  • raw query support for MongoDB in [3.9.0](https://github.com/prisma/prisma/releases/tag/3.9.0)
  • filters in embedded documents as an Experimental Feature in [3.11.0](https://github.com/prisma/prisma/releases/tag/3.11.0)
  • order by embedded documents in [3.11.0](https://github.com/prisma/prisma/releases/tag/3.11.0)
| [3.12.0](https://github.com/prisma/prisma/releases/tag/3.12.0) | -| [`microsoftSqlServer`](/orm/overview/databases/sql-server) | [2.10.0](https://github.com/prisma/prisma/releases/tag/2.10.0) | [3.0.1](https://github.com/prisma/prisma/releases/tag/3.0.1) | -| [`namedConstraints`](/orm/prisma-schema/data-model/database-mapping#constraint-and-index-names) | [2.29.0](https://github.com/prisma/prisma/releases/tag/2.29.0) | [3.0.1](https://github.com/prisma/prisma/releases/tag/3.0.1) | -| [`referentialActions`](/orm/prisma-schema/data-model/relations/referential-actions) | [2.26.0](https://github.com/prisma/prisma/releases/tag/2.26.0) | [3.0.1](https://github.com/prisma/prisma/releases/tag/3.0.1) | -| [`orderByAggregateGroup`](/orm/prisma-client/queries/aggregation-grouping-summarizing#order-by-aggregate-group) | [2.21.0](https://github.com/prisma/prisma/releases/tag/2.21.0) | [3.0.1](https://github.com/prisma/prisma/releases/tag/3.0.1) | -| [`orderByRelation`](/orm/prisma-client/queries/filtering-and-sorting#sort-by-relation) |
  • [2.16.0](https://github.com/prisma/prisma/releases/tag/2.16.0)
  • order by aggregates of relations in [2.19.0](https://github.com/prisma/prisma/releases/tag/2.19.0)
| [3.0.1](https://github.com/prisma/prisma/releases/tag/3.0.1) | -| [`selectRelationCount`](/orm/prisma-client/queries/aggregation-grouping-summarizing#count-relations) | [2.20.0](https://github.com/prisma/prisma/releases/tag/2.20.0) | [3.0.1](https://github.com/prisma/prisma/releases/tag/3.0.1) | -| `napi` | [2.20.0](https://github.com/prisma/prisma/releases/tag/2.20.0) | [3.0.1](https://github.com/prisma/prisma/releases/tag/3.0.1) | -| [`groupBy`](/orm/reference/prisma-client-reference#groupby) | [2.14.0](https://github.com/prisma/prisma/releases/tag/2.14.0) | [2.20.0](https://github.com/prisma/prisma/releases/tag/2.20.0) | -| [`createMany`](/orm/reference/prisma-client-reference#createmany) | [2.16.0](https://github.com/prisma/prisma/releases/tag/2.16.0) | [2.20.0](https://github.com/prisma/prisma/releases/tag/2.20.0) | -| [`nativeTypes`](/orm/prisma-schema/data-model/models#native-types-mapping) | [2.11.0](https://github.com/prisma/prisma/releases/tag/2.11.0) | [2.17.0](https://github.com/prisma/prisma/releases/tag/2.17.0) | -| [`uncheckedScalarInputs`](/orm/prisma-client/queries/relation-queries#create-a-single-record-and-multiple-related-records) | [2.11.0](https://github.com/prisma/prisma/releases/tag/2.11.0) | [2.15.0](https://github.com/prisma/prisma/releases/tag/2.15.0) | -| [`transactionApi`](/orm/prisma-client/queries/transactions#the-transaction-api) | [2.1.0](https://github.com/prisma/prisma/releases/tag/2.1.0) | [2.11.0](https://github.com/prisma/prisma/releases/tag/2.11.0) | -| [`connectOrCreate`](/orm/reference/prisma-client-reference#connectorcreate) | [2.1.0](https://github.com/prisma/prisma/releases/tag/2.1.0) | [2.11.0](https://github.com/prisma/prisma/releases/tag/2.11.0) | -| [`atomicNumberOperations`](/orm/reference/prisma-client-reference#atomic-number-operations) | [2.6.0](https://github.com/prisma/prisma/releases/tag/2.6.0) | [2.10.0](https://github.com/prisma/prisma/releases/tag/2.10.0) | -| [`insensitiveFilters` (PostgreSQL)](/orm/prisma-client/queries/filtering-and-sorting#case-insensitive-filtering) | [2.5.0](https://github.com/prisma/prisma/releases/tag/2.5.0) | [2.8.0](https://github.com/prisma/prisma/releases/tag/2.8.0) | -| [`middlewares`](/orm/prisma-client/client-extensions/middleware) | [2.3.0](https://github.com/prisma/prisma/releases/tag/2.3.0) | [2.5.0](https://github.com/prisma/prisma/releases/tag/2.5.0) | -| [`aggregateApi`](/orm/prisma-client/queries/aggregation-grouping-summarizing#aggregate) | [2.2.0](https://github.com/prisma/prisma/releases/tag/2.2.0) | [2.5.0](https://github.com/prisma/prisma/releases/tag/2.5.0) | -| [`distinct`](/orm/reference/prisma-client-reference#distinct) | [2.3.0](https://github.com/prisma/prisma/releases/tag/2.3.0) | [2.5.0](https://github.com/prisma/prisma/releases/tag/2.5.0) | +| Feature | Released into Preview | Released into General Availability | +| -------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | +| `jsonProtocol` | [4.11.0](https://github.com/prisma/prisma/releases/tag/4.11.0) | [5.0.0](https://github.com/prisma/prisma/releases/tag/5.0.0) | +| [`extendedWhereUnique`](/orm/reference/prisma-client-reference#filter-on-non-unique-fields-with-userwhereuniqueinput) | [4.5.0](https://github.com/prisma/prisma/releases/tag/4.5.0) | [5.0.0](https://github.com/prisma/prisma/releases/tag/5.0.0) | +| [`fieldReference`](/orm/reference/prisma-client-reference#compare-columns-in-the-same-table) | [4.3.0](https://github.com/prisma/prisma/releases/tag/4.3.0) | [5.0.0](https://github.com/prisma/prisma/releases/tag/5.0.0) | +| [`clientExtensions`](/orm/prisma-client/client-extensions) | [4.7.0](https://github.com/prisma/prisma/releases/tag/4.7.0) | [4.16.0](https://github.com/prisma/prisma/releases/tag/4.16.0) | +| [`filteredRelationCount`](/orm/prisma-client/queries/aggregation-grouping-summarizing#filter-the-relation-count) | [4.3.0](https://github.com/prisma/prisma/releases/tag/4.3.0) | [4.16.0](https://github.com/prisma/prisma/releases/tag/4.16.0) | +| [`orderByNulls`](/orm/prisma-client/queries/filtering-and-sorting#sort-with-null-records-first-or-last) | [4.1.0](https://github.com/prisma/prisma/releases/tag/4.1.0) | [4.16.0](https://github.com/prisma/prisma/releases/tag/4.16.0) | +| [`referentialIntegrity`](/orm/prisma-schema/data-model/relations/relation-mode) | [3.1.1](https://github.com/prisma/prisma/releases/tag/3.1.1) | [4.7.0](https://github.com/prisma/prisma/releases/tag/4.7.0) | +| [`interactiveTransactions`](/orm/prisma-client/queries/transactions#interactive-transactions) | [2.29.0](https://github.com/prisma/prisma/releases/tag/2.29.0) |
  • [4.7.0](https://github.com/prisma/prisma/releases/tag/4.7.0)
  • with Prisma Accelerate [5.1.1](https://github.com/prisma/prisma/releases/tag/5.1.1)
| +| [`extendedIndexes`](/orm/prisma-schema/data-model/indexes) | [3.5.0](https://github.com/prisma/prisma/releases/tag/3.5.0) | [4.0.0](https://github.com/prisma/prisma/releases/tag/4.0.0) | +| [`filterJson`](/orm/prisma-client/special-fields-and-types/working-with-json-fields#filter-on-a-json-field) | [2.23.0](https://github.com/prisma/prisma/releases/tag/2.23.0) | [4.0.0](https://github.com/prisma/prisma/releases/tag/4.0.0) | +| [`improvedQueryRaw`](/orm/prisma-client/queries/raw-database-access/raw-queries#raw-query-type-mapping) | [3.14.0](https://github.com/prisma/prisma/releases/tag/3.14.0) | [4.0.0](https://github.com/prisma/prisma/releases/tag/4.0.0) | +| [`cockroachdb`](/orm/overview/databases/cockroachdb) |
  • [3.9.0](https://github.com/prisma/prisma/releases/tag/3.9.0)
  • migrations in CockroachDB in [3.11.0](https://github.com/prisma/prisma/releases/tag/3.11.0)
| [3.14.0](https://github.com/prisma/prisma/releases/tag/3.14.0) | +| [`mongodb`](/orm/overview/databases/mongodb) |
  • [2.27.0](https://github.com/prisma/prisma/releases/tag/2.27.0)
  • introspection of MongoDB in [3.2.0](https://github.com/prisma/prisma/releases/tag/3.2.0)
  • introspection of embedded documents in [3.4.0](https://github.com/prisma/prisma/releases/tag/3.4.0)
  • MongoDB embedded documents in [3.10.0](https://github.com/prisma/prisma/releases/tag/3.10.0)
  • introspection of embedded documents in [3.10.0](https://github.com/prisma/prisma/releases/tag/3.10.0)
  • raw query support for MongoDB in [3.9.0](https://github.com/prisma/prisma/releases/tag/3.9.0)
  • filters in embedded documents as an Experimental Feature in [3.11.0](https://github.com/prisma/prisma/releases/tag/3.11.0)
  • order by embedded documents in [3.11.0](https://github.com/prisma/prisma/releases/tag/3.11.0)
| [3.12.0](https://github.com/prisma/prisma/releases/tag/3.12.0) | +| [`microsoftSqlServer`](/orm/overview/databases/sql-server) | [2.10.0](https://github.com/prisma/prisma/releases/tag/2.10.0) | [3.0.1](https://github.com/prisma/prisma/releases/tag/3.0.1) | +| [`namedConstraints`](/orm/prisma-schema/data-model/database-mapping#constraint-and-index-names) | [2.29.0](https://github.com/prisma/prisma/releases/tag/2.29.0) | [3.0.1](https://github.com/prisma/prisma/releases/tag/3.0.1) | +| [`referentialActions`](/orm/prisma-schema/data-model/relations/referential-actions) | [2.26.0](https://github.com/prisma/prisma/releases/tag/2.26.0) | [3.0.1](https://github.com/prisma/prisma/releases/tag/3.0.1) | +| [`orderByAggregateGroup`](/orm/prisma-client/queries/aggregation-grouping-summarizing#order-by-aggregate-group) | [2.21.0](https://github.com/prisma/prisma/releases/tag/2.21.0) | [3.0.1](https://github.com/prisma/prisma/releases/tag/3.0.1) | +| [`orderByRelation`](/orm/prisma-client/queries/filtering-and-sorting#sort-by-relation) |
  • [2.16.0](https://github.com/prisma/prisma/releases/tag/2.16.0)
  • order by aggregates of relations in [2.19.0](https://github.com/prisma/prisma/releases/tag/2.19.0)
| [3.0.1](https://github.com/prisma/prisma/releases/tag/3.0.1) | +| [`selectRelationCount`](/orm/prisma-client/queries/aggregation-grouping-summarizing#count-relations) | [2.20.0](https://github.com/prisma/prisma/releases/tag/2.20.0) | [3.0.1](https://github.com/prisma/prisma/releases/tag/3.0.1) | +| `napi` | [2.20.0](https://github.com/prisma/prisma/releases/tag/2.20.0) | [3.0.1](https://github.com/prisma/prisma/releases/tag/3.0.1) | +| [`groupBy`](/orm/reference/prisma-client-reference#groupby) | [2.14.0](https://github.com/prisma/prisma/releases/tag/2.14.0) | [2.20.0](https://github.com/prisma/prisma/releases/tag/2.20.0) | +| [`createMany`](/orm/reference/prisma-client-reference#createmany) | [2.16.0](https://github.com/prisma/prisma/releases/tag/2.16.0) | [2.20.0](https://github.com/prisma/prisma/releases/tag/2.20.0) | +| [`nativeTypes`](/orm/prisma-schema/data-model/models#native-types-mapping) | [2.11.0](https://github.com/prisma/prisma/releases/tag/2.11.0) | [2.17.0](https://github.com/prisma/prisma/releases/tag/2.17.0) | +| [`uncheckedScalarInputs`](/orm/prisma-client/queries/relation-queries#create-a-single-record-and-multiple-related-records) | [2.11.0](https://github.com/prisma/prisma/releases/tag/2.11.0) | [2.15.0](https://github.com/prisma/prisma/releases/tag/2.15.0) | +| [`transactionApi`](/orm/prisma-client/queries/transactions#the-transaction-api) | [2.1.0](https://github.com/prisma/prisma/releases/tag/2.1.0) | [2.11.0](https://github.com/prisma/prisma/releases/tag/2.11.0) | +| [`connectOrCreate`](/orm/reference/prisma-client-reference#connectorcreate) | [2.1.0](https://github.com/prisma/prisma/releases/tag/2.1.0) | [2.11.0](https://github.com/prisma/prisma/releases/tag/2.11.0) | +| [`atomicNumberOperations`](/orm/reference/prisma-client-reference#atomic-number-operations) | [2.6.0](https://github.com/prisma/prisma/releases/tag/2.6.0) | [2.10.0](https://github.com/prisma/prisma/releases/tag/2.10.0) | +| [`insensitiveFilters` (PostgreSQL)](/orm/prisma-client/queries/filtering-and-sorting#case-insensitive-filtering) | [2.5.0](https://github.com/prisma/prisma/releases/tag/2.5.0) | [2.8.0](https://github.com/prisma/prisma/releases/tag/2.8.0) | +| [`middlewares`](/orm/prisma-client/client-extensions/middleware) | [2.3.0](https://github.com/prisma/prisma/releases/tag/2.3.0) | [2.5.0](https://github.com/prisma/prisma/releases/tag/2.5.0) | +| [`aggregateApi`](/orm/prisma-client/queries/aggregation-grouping-summarizing#aggregate) | [2.2.0](https://github.com/prisma/prisma/releases/tag/2.2.0) | [2.5.0](https://github.com/prisma/prisma/releases/tag/2.5.0) | +| [`distinct`](/orm/reference/prisma-client-reference#distinct) | [2.3.0](https://github.com/prisma/prisma/releases/tag/2.3.0) | [2.5.0](https://github.com/prisma/prisma/releases/tag/2.5.0) | diff --git a/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/800-upgrading-to-prisma-3/index.mdx b/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/800-upgrading-to-prisma-3/index.mdx index cc8117a449..ed4114d024 100644 --- a/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/800-upgrading-to-prisma-3/index.mdx +++ b/content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/800-upgrading-to-prisma-3/index.mdx @@ -128,7 +128,7 @@ They also do not apply to the `array_contains` operator because there can only b -## Upgrading the `prisma` and `@prisma/client` packages to version 3 +## Upgrading the `prisma` and `@prisma/client` packages to Prisma ORM 3 To upgrade from version 2.x to 3.x, you need to update both the `prisma` and `@prisma/client` packages. Both the `prisma` and `@prisma/client` packages install with a caret `^` in their version number to safe guard against breaking changes. diff --git a/content/200-orm/800-more/400-comparisons/04-prisma-and-drizzle.mdx b/content/200-orm/800-more/400-comparisons/04-prisma-and-drizzle.mdx index 760e45db94..7d429db8bd 100644 --- a/content/200-orm/800-more/400-comparisons/04-prisma-and-drizzle.mdx +++ b/content/200-orm/800-more/400-comparisons/04-prisma-and-drizzle.mdx @@ -441,7 +441,7 @@ These products work hand-in-hand with Prisma ORM to offer comprehensive data too Both Drizzle and Prisma ORM have cases where users want to do something not directly supported by the library. Drizzle relies on the expressiveness of SQL to avoid these cases, while Prisma ORM has [Prisma Client extensions](/orm/prisma-client/client-extensions) to allow any user to add additional behaviors to their instance of Prisma Client. These extensions are also shareable, meaning teams can develop them for use across their projects or even for use by other teams. -While Drizzle is a relatively new product, Prisma ORM was [released in 2021](https://www.prisma.io/blog/prisma-the-complete-orm-inw24qjeawmb) and is well established in the JavaScript/TypeScript space. It has proven value , many companies trust [Prisma in production](http://prisma.io/showcase). +While Drizzle is a relatively new product, Prisma ORM was [released in 2021](https://www.prisma.io/blog/prisma-the-complete-orm-inw24qjeawmb) and is well established in the JavaScript/TypeScript space. It has proven value , many companies trust [Prisma ORM in production](http://prisma.io/showcase). Prisma ORM is also included as the data layer tool of choice in many meta-frameworks and development platforms like [Amplication](https://amplication.com/), [Wasp](https://wasp-lang.dev/), [RedwoodJS](https://redwoodjs.com/), [KeystoneJS](https://keystonejs.com/), [Remix](https://remix.run/) and the [t3 stack](https://create.t3.gg/). @@ -454,6 +454,7 @@ Thanks to its maturity, Prisma's community has developed a [plethora of useful t - [`jest-prisma`](https://github.com/Quramy/jest-prisma): Environment for Prisma integrated testing with [Jest](https://jestjs.io/). - [`prisma-pothos-types`](https://github.com/hayes/pothos/tree/main/packages/plugin-prisma): Creates GraphQL types based on Prisma models when using [GraphQL Pothos](https://github.com/hayes/pothos/tree/main). - [`prisma-trpc-generator`](https://github.com/omar-dulaimi/prisma-trpc-generator): Creates [tRPC](https://trpc.io/) routers from your Prisma schema. +- [`@cerbos/orm-prisma`](https://github.com/cerbos/query-plan-adapters/tree/main/prisma): Filter data based on authorization policies from [Cerbos](https://cerbos.dev). ## Database support diff --git a/content/200-orm/800-more/450-migrating-to-prisma/01-migrate-from-typeorm.mdx b/content/200-orm/800-more/450-migrating-to-prisma/01-migrate-from-typeorm.mdx index ee6daa8a59..e04aba8ab3 100644 --- a/content/200-orm/800-more/450-migrating-to-prisma/01-migrate-from-typeorm.mdx +++ b/content/200-orm/800-more/450-migrating-to-prisma/01-migrate-from-typeorm.mdx @@ -1116,7 +1116,5 @@ This would also result in a more ergonomic and less verbose Prisma Client API to If your database provider requires tables to have primary keys then you have to use explicit syntax, and manually create the join model with a primary key. - This is because relation tables (JOIN tables) created by Prisma ORM (expressed via - `@relation`) for many-to-many relations using implicit syntax do not have - primary keys. + This is because relation tables (JOIN tables) created by Prisma ORM (expressed via `@relation`) for many-to-many relations using implicit syntax do not have primary keys. 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 c42e174863..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 @@ -1,7 +1,7 @@ --- -title: 'Best practices for using Prisma Client with Next.js' -metaTitle: 'Best practices for using Prisma Client with Next.js' -metaDescription: 'Best practices for using Prisma Client with Next.js' +title: 'Best practice for instantiating Prisma Client with Next.js' +metaTitle: 'Best practice for instantiating Prisma Client with Next.js' +metaDescription: 'Best practice for instantiating Prisma Client with Next.js' --- ## Problem @@ -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: @@ -71,20 +71,3 @@ export const getServerSideProps = async () => { return { props: { posts } } } ``` - -## Next.js caching - -When using Next.js, you may run into an issue where [only stale data is returned from certain routes](https://github.com/prisma/prisma/discussions/22934#discussioncomment-8374081). In these cases, it's important to [set the dynamic behavior of the route](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#dynamic) to `"force-dynamic"` so data is correctly returned from your Prisma Client queries. - -You can add `"force-dynamic"` like this: - -```ts -import { NextRequest, NextResponse } from 'next/server' -import prisma from './db' - -export const dynamic = 'force-dynamic' - -export async function GET(request: NextRequest, response: NextResponse) { - // your code would go here -} -``` diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/430-nextjs-prisma-client-dynamic.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/430-nextjs-prisma-client-dynamic.mdx new file mode 100644 index 0000000000..820b00a96c --- /dev/null +++ b/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/430-nextjs-prisma-client-dynamic.mdx @@ -0,0 +1,28 @@ +--- +title: 'Best practices for using Prisma Client with Next.js and Next.js Data Cache' +metaTitle: 'Best practices for using Prisma Client with Next.js and Next.js Data Cache' +metaDescription: 'Learn best practices to avoid issues with route caching in Next.js' +--- + +## Problem + +When deploying a Next.js app, you may run into an issue where your queries are not updating or displaying the correct content. Or, you may find that it takes a long time for newly created objects to show up in your queries. + +In these cases, you are most likely seeing data persisted in the [Next.js Data Cache](https://nextjs.org/docs/app/building-your-application/caching#data-cache). Any `fetch` request has its result cached by default, leading to possibly unwanted results as Prisma uses `fetch` internally. + +## Solution + +To opt-out of the Next.js Data Cache, you can [disable caching for a specific route](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#dynamic) using the `"force-dynamic"` config option so that up to date data is always returned and no caching happens. + +You can add `"force-dynamic"` like this: + +```ts +import { NextRequest, NextResponse } from 'next/server' +import prisma from './db' + +export const dynamic = 'force-dynamic' + +export async function GET(request: NextRequest, response: NextResponse) { + // your code would go here +} +``` diff --git a/content/300-accelerate/200-getting-started.mdx b/content/300-accelerate/200-getting-started.mdx index f4c5fad94f..25d69204f1 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 @@ -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' diff --git a/content/300-accelerate/500-limitations.mdx b/content/300-accelerate/500-limitations.mdx index b12895f10b..9b737b3f78 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/600-faq.mdx b/content/300-accelerate/600-faq.mdx index 259bb9267c..2546e8ca05 100644 --- a/content/300-accelerate/600-faq.mdx +++ b/content/300-accelerate/600-faq.mdx @@ -96,4 +96,20 @@ Even without using Accelerate's global cache, you can still greatly benefit from ## Can I use Accelerate with other ORMs/query builders/drivers? -No. We currently do not have any plans for supporting other ORMs/query builders or drivers. However, if you're interested in support for other libraries, feel free to reach out and let us know in our [Discord](https://pris.ly/discord) community in the `#accelerate-feedback` channel. +No. We currently do not have any plans for supporting other ORMs/query builders or drivers. However, if you're interested in support for other libraries, feel free to reach out and let us know in our [Discord](https://pris.ly/discord) community in the `#help-and-questions` channel. + +## What is the maximum allowed value for the `ttl` parameter when configuring `cacheStrategy`? + +The [Time-to-live](/accelerate/caching#time-to-live-ttl) (`ttl`) parameter can be set for up to a _year_. However, it's important to note that items within the cache may be evicted if they are not frequently accessed. + +Based on our experimentation, we’ve seen cache items persist for around 18 hours. While items may remain in the cache for an extended period if they are actively accessed, there is no guarantee. + +> **Note**: Even frequently accessed items may occasionally be evicted from the cache. It's unlikely for an item to survive for up to or longer than a month, regardless of its activity level. + +## Why doesn’t Accelerate fall back to the direct connection string during a service disruption? + +In the rare event of a service disruption, falling back to a direct connection would bypass the connection pool. This could potentially deplete the database's available connections and cause other issues on the database level. + +If there is a service disruption, it's recommended to verify on the [status page](https://pris.ly/data-platform-status). You can reach out to one of Prisma's [support channels](https://www.prisma.io/docs/platform/support) for assistance. + +> **Note:** Additionally, it's worth noting that some edge function runtime environments may not support direct connections with Prisma ORM. For further details, refer to our [Edge functions documentation](https://www.prisma.io/docs/orm/prisma-client/deployment/edge/overview). diff --git a/content/300-accelerate/650-troubleshoot.mdx b/content/300-accelerate/650-troubleshoot.mdx new file mode 100644 index 0000000000..409ed6ce19 --- /dev/null +++ b/content/300-accelerate/650-troubleshoot.mdx @@ -0,0 +1,127 @@ +--- +title: 'Troubleshooting' +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. diff --git a/content/400-pulse/100-what-is-pulse.mdx b/content/400-pulse/100-what-is-pulse.mdx index 73a1fd96fe..4ee30935ef 100644 --- a/content/400-pulse/100-what-is-pulse.mdx +++ b/content/400-pulse/100-what-is-pulse.mdx @@ -8,14 +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. - + -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.

+## How Prisma Pulse works -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 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](/img/pulse/what-is-pulse.png) + +## What you can build with Prisma Pulse + +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. + +![Prisma Pulse use-cases](/img/pulse/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 1f1e289d7b..6181a130f9 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,164 +10,49 @@ toc: true ## Prerequisites -To participate in Pulse's Early Access program, you need to meet the following prerequisites: - -- 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.2` 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. - -You will also need a database with the following configurations: - -- 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. - -## 1. Database setup - -### 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. Drop the Timescale extension: - -```sql -DROP EXTENSION timescaledb; -``` - -2. Set the `[wal_level](https://www.postgresql.org/docs/current/runtime-config-wal.html)` to `logical`: - -```sql -ALTER SYSTEM SET wal_level = logical; -``` - -3. 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; -``` - -4. 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; -``` - -5. 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. - -## 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 - -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. +💡 Prisma Pulse currently supports PostgreSQL. We'd love to hear [which databases](https://tally.so/r/wLbb8G) you would like to see supported next. -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. +You'll need the following to integrate Pulse into your application: -### 3.1. Install the Pulse Prisma Client extension +- A [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. -In a project using [Prisma Client](/orm/prisma-client), run the following command to install the Pulse extension: +## 1. Enable Pulse -```terminal -npm install @prisma/extension-pulse -``` +Navigate to your Prisma Data Platform project, choose an environment, and enable Pulse. We'll connect to your database and verify connectivity during setup. -### Store your Pulse API key in your .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_secure_pulse_api_key" +> ``` -The Pulse extension requires you to use an API key. +## 2. Add Pulse to your application - +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. -You should have received an API key when you added Prisma Pulse to your project in the Platform Console. +### 2.1. Install the Pulse Client extension - + -In `.env`, add a variable named `PULSE_API_KEY`: +💡 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 -```env file=.env -PULSE_API_KEY="YOUR-API-KEY" + -# Example: -# PULSE_API_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcGlfa2V5IjoiNGMxNzM0MGItMmFhYy00MGMxLWE1ZDctNzYyNmRjNjg3NjM4IiwidGVuYW50X2lkIjoiY2VhZjE0NThkZGUyYzJmNTU0ZmNkNTI2MmFmOWY1ODljMWJiZmRhNDU0N2UxMjM1ODk3MGQ2MGI1ZjRlNTU0OCIsImludGVybmFsX3NlY3JldCI6ImM1ZTcxYjJhLTE0NzdawdwDliZS1hM2IzLTczODFkNDM5ZmEwZSJ9.wCUlghC_suFBr2vnk0q_5I8iRNRDyEQo0W9rnhf6mCw" +Install the latest version of Prisma Client and the Pulse Client extension + +```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' @@ -178,32 +63,46 @@ const prisma = new PrismaClient().$extends( ) ``` -### 3.3. Create your first Pulse subscription + + +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 Pulse subscription -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. +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 - } + 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() ``` - +All done! You've successfully added Pulse to your application. Explore next steps to learn more. -Refer to the [API Reference](/pulse/api-reference) section for more detail on the filtering options available to the `subscribe()` method. +## Next steps - +[Navigate to the API section](/pulse/api-reference) to explore available filtering options for Pulse's `subscribe()` method. + +```ts +const subscription = await prisma.notification.subscribe({ + create: { + userId: 123, // subscribe to all notifications created for the user with ID 123 + }, +}) +``` + +## Need help? + +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. 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..f4dee6dea4 --- /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: + + ![](/img/pulse/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..84f6780d2b --- /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](/img/pulse/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](/img/pulse/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](/img/pulse/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..57a907e869 --- /dev/null +++ b/content/400-pulse/250-database-setup/300-railway.mdx @@ -0,0 +1,135 @@ +--- +title: 'Railway' +metaTitle: 'Prisma Pulse: Railway' +metaDescription: 'Instructions to use Railway with Prisma Pulse' +tocDepth: 3 +toc: true +--- + + + +Railway provides a useful feature known as [templates](https://railway.app/templates) to facilitate quick project setup. These templates allow users to package a service or a group of services into a format that can be easily reused and shared. We have two templates for Prisma Pulse that you can use: + +- [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 with template: "Prisma Pulse DB Only" + +### Overview + +This section provides step-by-step instructions for setting up a Pulse-ready PostgreSQL database using the Railway template called: [Prisma Pulse DB Only](https://railway.app/template/pulse-pg). + +The template consists of two [services](https://docs.railway.app/reference/services): + +- **Postgres**: A PostgreSQL database that you'll be able to use with Prisma Pulse after going through the setup instructions. +- **restart-and-delete-me**: This service contains a [script](https://github.com/prisma/pulse-railway-pg-config/blob/main/config-db.ts) that's executed once and configures the PostgreSQL database to make it usable with Prisma Pulse. Once the script has been executed, the instructions will tell you to delete this service since it won't be needed any more. + +### Instructions + +1. Deploy the [template](https://railway.app/template/pulse-pg) on Railway. +2. Once the deployment has finished, 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 deployment'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: + ```terminal no-copy + All done please restart the database and delete this service. + Here is the DATABASE_URL + postgresql://postgres:password@roundhouse.proxy.rlwy.net:28606/railway + ``` + > **Note**: + > The `DATABASE_URL` can also be found by clicking on the **Postgres** Service and navigating to the **Variables** tab, then clicking the copy icon next to `DATABASE_URL` environment variable value. + > ![](/img/pulse/railway-database-url.png) +6. Copy the `DATABASE_URL` connection string and save it for later. Then restart your Railway database for the changes to be reflected: + 1. Click on the **Postgres** service that represents your deployed database. + 2. Navigate to the **Deployments** tab. + 3. Click on 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. +9. You now have a Pulse-compatible PostgreSQL database running on Railway. You can now follow the instructions on the [Getting started](/pulse/getting-started) page. + +## Setup with template: "Prisma Pulse DB & App" + +### Overview + +This section provides step-by-step instructions for setting up a Pulse starter project with a Pulse-ready PostgreSQL database using the Railway template called: [Prisma Pulse DB & App](https://railway.app/template/pulse-starter). +The template consists of three [services](https://docs.railway.app/reference/services): + +- **Pulse-Starter**: A Typescript app with a basic setup for using Prisma Pulse. You can find the repo for it [on GitHub](https://github.com/prisma/pulse-starter/tree/main). +- **Postgres**: A PostgreSQL database that you'll be able to use with Prisma Pulse after going through the setup instructions. +- **restart-and-delete-me**: This service contains a [script](https://github.com/prisma/pulse-railway-pg-config/blob/main/config-db.ts) that's executed once and configures the PostgreSQL database to make it usable with Prisma Pulse. Once the script has been executed, the instructions will tell you to delete this service since it won't be needed any more. + +### Instructions + +1. Deploy the [template](https://railway.app/template/pulse-starter) on Railway. +2. You'll be navigated to a page prompting configuration for both the **restart-db-then-delete-me** and **pulse-starter** service: + ![Configure Railway template](/img/pulse/railway-template-configure.png) + 1. For the **restart-db-then-delete-me** service, click on the **Configure** button and then save the configuration by clicking on **Save Config**. + 2. On the **pulse-starter** service, locate and click the **Configure** button. Within the **Environment variables** section, you'll find an option to include the `PULSE_API_KEY` environment variable. Keep the `PULSE_API_KEY` field blank for the time being. Once you've set up the database and obtained the database URL from the [Prisma Data Platform](https://console.prisma.io/), you can then add the `PULSE_API_KEY` to the **pulse-starter** service. With the empty field for the Pulse API key, click **Save Config**. + 3. Click on the **Deploy** button. +3. To set up the database and make it Pulse-ready, complete the steps outlined in the [previous section](#setup-with-template-prisma-pulse-db-only), starting from **step 2.** till **step 8.**, then follow the instructions below. +4. Go to the [Platform Console](https://console.prisma.io/) and select the project in which you want to activate Pulse. If you don't have a project yet, create a new project via the **New project** button. +5. Navigate to the project's environment in which Pulse should be activated. If you just created a new project, the only available environment is the **Production** environment. +6. Click **Enable Pulse** on the environment's page. +7. Paste the `DATABASE_URL` that you acquired before into the **Database connection string** field. Then, finish the process by clicking **Enable Pulse**. +8. Pulse is now enabled in your project's environment. Click **Generate API key** to obtain the API key that you need in order to use Pulse in your TypeScript starter app. +9. Save the `PULSE_API_KEY` for later and click **I've securely stored my connection string**. +10. Back in the Railway UI, click on the **pulse-starter** service. + > **Note**: You'll likely find that the build failed for the **pulse-starter** service. This is because the Prisma Pulse API key wasn't provided. Do not worry, this is to be expected and not a problem for the next steps. +11. Click on the **Variables** tab. +12. Create your `PULSE_API_KEY` environment variable: Click the **New Variable** button, create the `PULSE_API_KEY` environment variable, and then paste the value of the `PULSE_API_KEY` that you obtained in the Platform Console. Then save the changes by clicking the **Add** button. +13. With the `PULSE_API_KEY` environment variable in place, you need to rebuild the **pulse-starter** service for the environment variable to take effect: +14. Click on the **Deployments** tab. +15. Click on the three-dots menu on the deployment that failed. Then click **Redeploy**. +16. When the deployment starts, click the **View Logs** button. +17. Then click on the **Deploy Logs** tab to follow the deployment of the Pulse starter app. + +Once the deployment is finished, your Pulse starter app should be running and any database events events will be logged under the **Deploy Logs** tab of the **pulse-starter** service. + +To see an event in action, you need to make changes to the `User` table. You can follow the steps below to do that from the Railway UI: + +1. Click on the **Postgres** service on your Railway project. +2. Click on the **Data** tab. +3. Select the **User** table and click **Add Row**. +4. Fill out an **email** and a **name**, then click **Insert**. +5. Return to the **Deploy Logs** of your **pulse-starter** service. +6. You should be able to see an output from Prisma Pulse for the user being created: + ```json + just received an event: { + action: "create", + created: { id: 1, email: "test", name: "test@test.io" }, + id: 03/34334, + modelName: "User" + } + ``` + +## Setup without using a template + +1. Change the PostgreSQL database settings + + You can run these queries using a tool such as [pgAdmin](https://www.pgadmin.org/), [dbeaver](https://dbeaver.io/), 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. You have to restart your database for the changes to be reflected. To restart your database using the Railway UI: + 1. Click on your database. + 2. Navigate to the **Deployments** tab. + 3. Click on the three-dots menu on the latest deployment and click the **Restart** option. +3. 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 to your PostgreSQL database. +4. You now have a Pulse-compatible PostgreSQL database running on Railway. You can now follow the instructions on the [Getting started](/pulse/getting-started) page. 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..bc53fbba84 --- /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: + + ![](/img/pulse/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..bdaa8c44b8 --- /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](/img/pulse/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..1e01beb655 --- /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 23358f4ad1..378afa6605 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 1f2ecb8e4e..11f5e9f706 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_max_heading_level: 4 @@ -47,7 +47,7 @@ Inside of the `subscribe()` method you can use filters to get specific events an You can use the `create` filter to retrieve all _create_ events on a table. A create event is triggered when a new record is created in a table. -Pulse returns the values of the new record as an object named `after`. +Pulse returns the values of the new record as an object named `created`. This represents the state of the record _after_ the create event. ##### Example @@ -66,7 +66,7 @@ const subscription = await prisma.user.subscribe({ ```ts no-copy { action: 'create', - after: { + created: { id: 1, email: 'marc@prisma.io', name: 'Marc' @@ -115,7 +115,7 @@ const subscription = await prisma.user.subscribe({ You can use the `delete` filter to retrieve all _delete_ events on a table. A delete event is triggered when a record has been removed from the database. -Pulse returns the values of the changed record as an object named `before`. This represents the state of the record _before_ the change event. +Pulse returns the values of the changed record as an object named `deleted`. This represents the state of the record _before_ the change event. ##### Example @@ -134,7 +134,7 @@ const subscription = await prisma.user.subscribe({ ```ts no-copy { action: 'delete', - before: { + deleted: { id: 1, email: '', name: null @@ -156,16 +156,48 @@ ALTER TABLE public."User" REPLICA IDENTITY FULL; +## `stop` + +Allows you to explicitly stop subscriptions and close the connection. This is needed to ensure that the limited number of subscriptions allowed per table is not exhausted. + +```ts +async function main() { + // Subscribe to new events on the `user` table + const subscription = await prisma.user.subscribe({}) + + // Set a timeout to the subscription after 60 seconds. + // Explicitly stopping the subscriptions and closing the connection is needed + // to not exhaust the limited number of subscriptions allowed per table. + + setTimeout(() => { + console.log('Stopping the subscription.') + subscription.stop() + }, 60000) + + // Waiting loop that prints new events when something changes in the database + for await (const event of subscription) { + console.log('new event:', event) // 'create', 'update', 'delete' + } +} + +main() +``` + ### Filter conditions and operators Pulse allows you to subscribe to change events based on filter conditions and operators. Pulse supports all of Prisma Client’s [supported filter conditions and operators](/orm/reference/prisma-client-reference#filter-conditions-and-operators) except for `search` and `mode`. You also won't be able to define filters that reference other models via relations. -You must wrap your filter criteria inside a `before` or `after` object depending on the type of event your subscription is listening for: +You may have to wrap your filter criteria inside a `after` object depending on the type of event your subscription is listening for: + +- `after`: `update` events -- `before`: `delete` events -- `after`: `create` and `update` events +This makes it explicit that the specified filter criteria apply to the `after` state of the change event. -This makes it explicit that the specified filter criteria apply to the `before` or `after` state of the change event. + + +All [`create`](#create) event results implicitly represent the `after` state of the change event. And all [`delete`](#delete) event results implicitly represent the `before` state of the change event. + + @@ -179,38 +211,6 @@ Using a filter inside of `after` will return changed records that match your fil ##### Examples -Get `create` events where the value of name is equal to `'Jim'` after the event has occurred: - - - - -```ts -const subscription = await prisma.user.subscribe({ - create: { - after: { - name: 'Jim', - }, - }, -}) -``` - - - - -```ts no-copy -{ - action: 'create', - after: { - id: 6, - email: 'test@test.com', - name: 'Jim' - } -} -``` - - - - Get `update` events where the value of name is equal to `Jim` after the event has occurred: @@ -242,47 +242,3 @@ const subscription = await prisma.user.subscribe({ - -#### Usage in the before state filter - -Using a filter inside of `before` will return changed records that match your filter criteria as applied to the state of the record before the change event. - -##### Example - -Get delete events where the value of name was equal to Marc. - - - - -```ts -const subscription = await prisma.user.subscribe({ - delete: { - before: { - name: 'Jim', - }, - }, -}) -``` - - - - -```ts no-copy -{ - action: 'update', - after: { - id: 6, - email: 'updated@test.com', - name: 'Jim', - } -} -``` - - - - - - -Specifying a filter condition for delete events only works if you’ve set the table’s `REPLICA IDENTITY` to `FULL`. See [this section](/pulse/api-reference#delete) for more details. - - diff --git a/content/400-pulse/500-current-limitations.mdx b/content/400-pulse/500-current-limitations.mdx deleted file mode 100644 index c851c6c274..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`. diff --git a/content/400-pulse/500-known-limitations.mdx b/content/400-pulse/500-known-limitations.mdx new file mode 100644 index 0000000000..6462eb65ba --- /dev/null +++ b/content/400-pulse/500-known-limitations.mdx @@ -0,0 +1,62 @@ +--- +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. + +## 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. diff --git a/content/400-pulse/600-faq.mdx b/content/400-pulse/600-faq.mdx index ce494f08a5..0ecd2fef59 100644 --- a/content/400-pulse/600-faq.mdx +++ b/content/400-pulse/600-faq.mdx @@ -1,48 +1,54 @@ --- 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? +## What databases are supported with 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. +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/database-setup/general-database-instructions#max_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 54ffd78365..bb0b149f7c 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 hide_table_of_contents: 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/index.mdx b/content/400-pulse/index.mdx index 9d30a4f614..037c76b73b 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.' hide_table_of_contents: true -earlyaccess: true sidebar_position: 0 --- @@ -15,4 +14,4 @@ sidebar_position: 0 ## In this section - \ No newline at end of file + diff --git a/content/500-platform/10-about.mdx b/content/500-platform/10-about.mdx index 964f742735..aec66b3179 100644 --- a/content/500-platform/10-about.mdx +++ b/content/500-platform/10-about.mdx @@ -11,6 +11,6 @@ Platform Console enables you to integrate the latest Prisma Data Platform produc - [Accelerate](/accelerate/what-is-accelerate): Global database cache with scalable connection pooling - [Pulse](/pulse/what-is-pulse): A managed Change Data Capture (CDC) service that enables real-time database subscriptions -[Launch Platform Console](https://console.prisma.io) +[Go to Platform Console](https://console.prisma.io) diff --git a/content/500-platform/60-platform-cli/20-commands.mdx b/content/500-platform/60-platform-cli/20-commands.mdx index cc2774dbb2..70e5c2bfe2 100644 --- a/content/500-platform/60-platform-cli/20-commands.mdx +++ b/content/500-platform/60-platform-cli/20-commands.mdx @@ -13,7 +13,7 @@ This document describes the Prisma Data Platform's integrated Prisma CLI command ## Getting started -To get started, ensure you have the [Prisma CLI](https://www.prisma.io/docs/orm/tools/prisma-cli#installation) updated to version `5.10.0` or later. This is necessary to access the Platform through the Prisma CLI. +To get started, ensure you have the [Prisma CLI](/orm/tools/prisma-cli) updated to version `5.10.0` or later. This is necessary to access the Platform through the Prisma CLI. diff --git a/content/500-platform/index.mdx b/content/500-platform/index.mdx index bda616fcab..6f5ab32094 100644 --- a/content/500-platform/index.mdx +++ b/content/500-platform/index.mdx @@ -11,3 +11,7 @@ sidebar_position: 0 Learn about the main concepts and workflows of the [Prisma Data Platform](https://prisma.io/data-platform/). + +## In this section + + diff --git a/static/img/pulse/add-group.png b/static/img/pulse/add-group.png new file mode 100644 index 0000000000..083ac2897d Binary files /dev/null and b/static/img/pulse/add-group.png differ diff --git a/static/img/pulse/aws-rds-create-parameter-group.png b/static/img/pulse/aws-rds-create-parameter-group.png new file mode 100644 index 0000000000..20e969cb77 Binary files /dev/null and b/static/img/pulse/aws-rds-create-parameter-group.png differ diff --git a/static/img/pulse/pulse-usecase.png b/static/img/pulse/pulse-usecase.png new file mode 100644 index 0000000000..2bc05b4742 Binary files /dev/null and b/static/img/pulse/pulse-usecase.png differ diff --git a/static/img/pulse/railway-database-url.png b/static/img/pulse/railway-database-url.png new file mode 100644 index 0000000000..565c9eab05 Binary files /dev/null and b/static/img/pulse/railway-database-url.png differ diff --git a/static/img/pulse/railway-template-configure.png b/static/img/pulse/railway-template-configure.png new file mode 100644 index 0000000000..a190ef7936 Binary files /dev/null and b/static/img/pulse/railway-template-configure.png differ diff --git a/static/img/pulse/replication-slot-submission.png b/static/img/pulse/replication-slot-submission.png new file mode 100644 index 0000000000..7815f39f95 Binary files /dev/null and b/static/img/pulse/replication-slot-submission.png differ diff --git a/static/img/pulse/set-logical-replication-parameter.png b/static/img/pulse/set-logical-replication-parameter.png new file mode 100644 index 0000000000..451aa42ab0 Binary files /dev/null and b/static/img/pulse/set-logical-replication-parameter.png differ diff --git a/static/img/pulse/supabase-direct-database-connection.png b/static/img/pulse/supabase-direct-database-connection.png new file mode 100644 index 0000000000..c7cbf59ab2 Binary files /dev/null and b/static/img/pulse/supabase-direct-database-connection.png differ diff --git a/static/img/pulse/what-is-pulse.png b/static/img/pulse/what-is-pulse.png new file mode 100644 index 0000000000..8443201104 Binary files /dev/null and b/static/img/pulse/what-is-pulse.png differ