From 1f77dd226f5f7d9705eb0fe0912eff033c80c702 Mon Sep 17 00:00:00 2001 From: Jon Harrell <4829245+jharrell@users.noreply.github.com> Date: Fri, 3 Jan 2025 12:12:06 -0600 Subject: [PATCH 1/6] Update documentation for ORM 6.2 Fixes #6565 --- For more details, open the [Copilot Workspace session](https://copilot-workspace.githubnext.com/prisma/docs/issues/6565?shareId=XXXX-XXXX-XXXX-XXXX). --- .../050-overview/500-databases/500-sqlite.mdx | 5 +- .../100-working-with-json-fields.mdx | 5 - .../100-prisma-schema-reference.mdx | 2 +- .../500-reference/350-database-features.mdx | 113 +++++++++--------- 4 files changed, 60 insertions(+), 65 deletions(-) diff --git a/content/200-orm/050-overview/500-databases/500-sqlite.mdx b/content/200-orm/050-overview/500-databases/500-sqlite.mdx index 9e8dd99f9a..0957f1b5d3 100644 --- a/content/200-orm/050-overview/500-databases/500-sqlite.mdx +++ b/content/200-orm/050-overview/500-databases/500-sqlite.mdx @@ -46,9 +46,12 @@ The SQLite connector maps the [scalar types](/orm/prisma-schema/data-model/model | `Float` | `REAL` | | `Decimal` | `DECIMAL` | | `DateTime` | `NUMERIC` | -| `Json` | Not supported | +| `Json` | \* | +| `Enum` | \* | | `Bytes` | `BLOB` | +> \* As SQLite does not have native `JSON` or `ENUM` types, these are implemented via shims and consistency is maintained by Prisma ORM. + ## Rounding errors on big numbers SQLite is a loosely-typed database. If your Schema has a field of type `Int`, then Prisma ORM prevents you from inserting a value larger than an integer. However, nothing prevents the database from directly accepting a bigger number. These manually-inserted big numbers cause rounding errors when queried. diff --git a/content/200-orm/200-prisma-client/200-special-fields-and-types/100-working-with-json-fields.mdx b/content/200-orm/200-prisma-client/200-special-fields-and-types/100-working-with-json-fields.mdx index 3601592a1a..f90354f107 100644 --- a/content/200-orm/200-prisma-client/200-special-fields-and-types/100-working-with-json-fields.mdx +++ b/content/200-orm/200-prisma-client/200-special-fields-and-types/100-working-with-json-fields.mdx @@ -5,8 +5,6 @@ metaDescription: 'How to read, write, and filter by Json fields.' tocDepth: 3 --- - - Use the [`Json`](/orm/reference/prisma-schema-reference#json) Prisma ORM field type to read, write, and perform basic filtering on JSON types in the underlying database. In the following example, the `User` model has an optional `Json` field named `extendedPetsData`: ```prisma highlight=6;normal @@ -35,7 +33,6 @@ Example field value: } ``` -> **Note**: The `Json` field is only supported if the [underlying database](/orm/overview) has a corresponding JSON data type. The `Json` field supports a few additional types, such as `string` and `boolean`. These additional types exist to match the types supported by [`JSON.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse): @@ -49,8 +46,6 @@ export declare type JsonValue = | JsonArray ``` - - ## Use cases for JSON fields Reasons to store data as JSON rather than representing data as related models include: 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 e782a27187..d7c90b5e0d 100644 --- a/content/200-orm/500-reference/100-prisma-schema-reference.mdx +++ b/content/200-orm/500-reference/100-prisma-schema-reference.mdx @@ -3357,7 +3357,7 @@ Defines an [enum](/orm/prisma-schema/data-model/models#defining-enums) . ### Remarks - Enums are natively supported by [PostgreSQL](https://www.postgresql.org/docs/current/datatype-enum.html) and [MySQL](https://dev.mysql.com/doc/refman/8.0/en/enum.html) -- Enums are implemented and enforced at Prisma ORM level in MongoDB +- Enums are implemented and enforced at Prisma ORM level in SQLite and MongoDB ### Naming conventions diff --git a/content/200-orm/500-reference/350-database-features.mdx b/content/200-orm/500-reference/350-database-features.mdx index 8ca4514a45..c22012a778 100644 --- a/content/200-orm/500-reference/350-database-features.mdx +++ b/content/200-orm/500-reference/350-database-features.mdx @@ -3,90 +3,87 @@ title: 'Database features matrix' metaTitle: 'Database features matrix' metaDescription: 'Learn which database features are supported in Prisma ORM and how they map to the different Prisma ORM tools.' wide: true -tocDepth: 3 --- - - This page gives an overview of the features which are provided by the databases that Prisma ORM supports. Additionally, it explains how each of these features can be used in Prisma ORM with pointers to further documentation. -> **Note**: If a feature is not supported natively by the database, it's also not available in Prisma ORM. - - - ## Relational database features This section describes which database features exist on the relational databases that are currently supported by Prisma ORM. The **Prisma schema** column indicates how a certain feature can be represented in the [Prisma schema](/orm/prisma-schema) and links to its documentation. Note that database features can be used in **Prisma Client** even though they might not yet be representable in the Prisma schema. +:::note + +These features are _only_ for relational databases. Supported features for NoSQL databases, like MongoDB, can [be found below](#nosql-database-features). + +::: + ### Constraints -| Constraint | PostgreSQL | Microsoft SQL Server | MySQL | SQLite | CockroachDB | Prisma schema | Prisma Client | Prisma Migrate | -| ------------- | :--------: | :------------------: | :---: | :----: | :---------: | :--------------------------------------------------------------------------------------: | :-----------: | :------------: | -| `PRIMARY KEY` | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | [`@id` and `@@id`](/orm/prisma-schema/data-model/models#defining-an-id-field) | ✔️ | ✔️ | -| `FOREIGN KEY` | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | [Relation fields](/orm/prisma-schema/data-model/relations#relation-fields) | ✔️ | ✔️ | -| `UNIQUE` | ✔️ | ✔️† | ✔️ | ✔️ | ✔️ | [`@unique` and `@@unique`](/orm/prisma-schema/data-model/models#defining-a-unique-field) | ✔️ | ✔️ | -| `CHECK` | ✔️ | ✔️ | ✔️\* | ✔️ | ✔️ | Not yet | ✔️ | Not yet | -| `NOT NULL` | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | [`?`](/orm/prisma-schema/data-model/models#type-modifiers) | ✔️ | ✔️ | -| `DEFAULT` | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | [`@default`](/orm/prisma-schema/data-model/models#defining-a-default-value) | ✔️ | ✔️ | +| Constraint | Supported | Prisma schema | Prisma Client | Prisma Migrate | +| ------------- | :-------: | :--------------------------------------------------------------------------------------: | :-----------: | :------------: | +| `PRIMARY KEY` | ✔️ | [`@id` and `@@id`](/orm/prisma-schema/data-model/models#defining-an-id-field) | ✔️ | ✔️ | +| `FOREIGN KEY` | ✔️ | [Relation fields](/orm/prisma-schema/data-model/relations#relation-fields) | ✔️ | ✔️ | +| `UNIQUE` | ✔️\* | [`@unique` and `@@unique`](/orm/prisma-schema/data-model/models#defining-a-unique-field) | ✔️ | ✔️ | +| `CHECK` | ✔️† | Not yet | ✔️ | Not yet | +| `NOT NULL` | ✔️ | [`?`](/orm/prisma-schema/data-model/models#type-modifiers) | ✔️ | ✔️ | +| `DEFAULT` | ✔️ | [`@default`](/orm/prisma-schema/data-model/models#defining-a-default-value) | ✔️ | ✔️ | -- \*In [MySQL 8 and higher](https://dev.mysql.com/doc/refman/8.0/en/create-table-check-constraints.html) -- † [Caveats apply when using the `UNIQUE` constraint with Microsoft SQL Server](/orm/overview/databases/sql-server#data-model-limitations) +> \* [Caveats apply when using the `UNIQUE` constraint with Microsoft SQL Server](/orm/overview/databases/sql-server#data-model-limitations) +> † Only supported in MySQL in [version 8 and higher](https://dev.mysql.com/doc/refman/8.0/en/create-table-check-constraints.html). ### Referential Actions (Delete and Update behaviors for foreign key references) -| Deletion behavior | PostgreSQL | Microsoft SQL Server | MySQL | SQLite | CockroachDB | Prisma schema | Prisma Client | Prisma Migrate | -| ----------------- | :--------: | :------------------: | :---: | :----: | :---------: | :-----------: | :-----------: | :------------: | -| `CASCADE` | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | **✔️**† | ✔️ | **✔️**† | -| `RESTRICT` | ✔️ | No | ✔️ | ✔️ | ✔️ | **✔️**† | ✔️ | **✔️**† | -| `NO ACTION` | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | **✔️**† | ✔️ | **✔️**† | -| `SET DEFAULT` | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | **✔️**† | ✔️ | **✔️**† | -| `SET NULL` | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | **✔️**† | ✔️ | **✔️**† | +| Deletion behavior | Supported | Prisma schema | Prisma Client | Prisma Migrate | +| ----------------- | :-------: | :-----------: | :-----------: | :------------: | +| `CASCADE` | ✔️ | ✔️ | ✔️ | ✔️ | +| `RESTRICT` | ✔️\* | ✔️ | ✔️ | ✔️ | +| `NO ACTION` | ✔️ | ✔️ | ✔️ | ✔️ | +| `SET DEFAULT` | ✔️ | ✔️ | ✔️ | ✔️ | +| `SET NULL` | ✔️ | ✔️ | ✔️ | ✔️ | -- † In [2.26.0](https://github.com/prisma/prisma/releases/tag/2.26.0) and later you can define [referential actions](/orm/prisma-schema/data-model/relations/referential-actions) on your relation fields. Referential actions determine what should happen to a record when a related record is deleted or updated. +> \* `RESTRICT` is not supported in Microsoft SQL Server. ### Indexes -| Index | PostgreSQL | Microsoft SQL Server | MySQL | SQLite | CockroachDB | Prisma schema | Prisma Client | Prisma Migrate | -| -------------- | :--------: | :------------------: | :---: | :----: | :---------: | :---------------------------------------------------------------------------------------------------------------------: | :-----------: | :------------: | -| `UNIQUE` | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | [`@unique` and `@@unique`](/orm/prisma-schema/data-model/models#defining-a-unique-field) | ✔️ | ✔️ | -| `USING` | ✔️ | No | No | No | ✔️ | [`type`](/orm/prisma-schema/data-model/indexes#configuring-the-access-type-of-indexes-with-type-postgresql)† | ✔️ | ✔️† | -| `WHERE` | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | Not yet | ✔️ | Not yet | -| `(expression)` | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | Not yet | ✔️ | Not yet | -| `INCLUDE` | ✔️ | ✔️ | No | No | ✔️ | Not yet | ✔️ | Not yet | - -- † Available in preview in 3.6.0 and later and in general availability in 4.0.0 and later, with the PostgreSQL connector only. +| Index | Supported | Prisma schema | Prisma Client | Prisma Migrate | +| -------------- | :-------------: | :---------------------------------------------------------------------------------------------------------: | :-----------: | :------------: | +| `UNIQUE` | ✔️ | [`@unique` and `@@unique`](/orm/prisma-schema/data-model/models#defining-a-unique-field) | ✔️ | ✔️ | +| `USING` | PostgreSQL only | [`type`](/orm/prisma-schema/data-model/indexes#configuring-the-access-type-of-indexes-with-type-postgresql) | ✔️ | ✔️ | +| `WHERE` | ✔️ | Not yet | ✔️ | Not yet | +| `(expression)` | ✔️ | Not yet | ✔️ | Not yet | +| `INCLUDE` | PostgreSQL and Microsoft SQL Server only | Not yet | ✔️ | Not yet | Algorithm specified via `USING`: -| Index type (Algorithm) | PostgreSQL | Microsoft SQL Server | MySQL | SQLite | CockroachDB | Prisma schema | Prisma Client | Prisma Migrate | -| ---------------------- | :--------: | :------------------: | :---: | :----: | :---------: | :-----------: | :-----------: | :------------: | -| B-tree | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️† | ✔️ | Not yet | -| Hash | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️† | ✔️ | Not yet | -| GiST | ✔️ | ✔️ | No | No | ✔️ | ✔️† | ✔️\* | Not yet | -| GIN | ✔️ | ✔️ | No | No | ✔️ | ✔️† | ✔️\* | Not yet | -| BRIN | ✔️ | ✔️ | No | No | ✔️ | ✔️† | ✔️\* | Not yet | -| SP-GiST | ✔️ | ✔️ | No | No | ✔️ | ✔️† | ✔️\* | Not yet | +| Index type (Algorithm) | Supported | Prisma schema | Prisma Client | Prisma Migrate | +| ---------------------- | :-------: | :-----------: | :-----------: | :------------: | +| B-tree | ✔️ | ✔️† | ✔️ | Not yet | +| Hash | ✔️ | ✔️† | ✔️ | Not yet | +| GiST | ✔️\* | ✔️† | ✔️\* | Not yet | +| GIN | ✔️\* | ✔️† | ✔️\* | Not yet | +| BRIN | ✔️\* | ✔️† | ✔️\* | Not yet | +| SP-GiST | ✔️\* | ✔️† | ✔️\* | Not yet | -- \* Only available if natively supported by database. +- \* Not supported for MySQL and SQLite - † Available with the PostgreSQL connector only in Prisma ORM versions `4.0.0` and later. ### Misc -| Feature | PostgreSQL | Microsoft SQL Server | MySQL | SQLite | CockroachDB | Prisma schema | Prisma Client | Prisma Migrate | -| --------------------------------- | :--------: | :------------------: | :---: | :----: | :---------: | :--------------------------------------------------------------------------------: | :-----------: | :------------: | -| Autoincrementing IDs | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | [`autoincrement()`](/orm/prisma-schema/data-model/models#defining-a-default-value) | ✔️ | ✔️ | -| Arrays | ✔️ | No | No | No | ✔️ | [`[]`](/orm/prisma-schema/data-model/models#type-modifiers) | ✔️\* | ✔️\* | -| Enums | ✔️ | No | ✔️ | No | ✔️ | [`enum`](/orm/prisma-schema/data-model/models#defining-enums) | ✔️\* | ✔️\* | -| Native database types | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | Not yet | -| SQL Views | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | Not yet | Not yet | Not yet | -| JSON support | ✔️ | **✔️**† | ✔️ | No | ✔️‡ | ✔️\* | ✔️\* | ✔️\* | -| Fuzzy/Phrase full text search | ✔️ | ✔️ | ✔️ | No | ✔️ | Not yet | Not yet | Not yet | -| Table inheritance | ✔️ | ✔️ | No | No | ✔️ | Not yet | ✔️\* | Not yet | -| Authorization and user management | ✔️ | ✔️ | ✔️ | No | ✔️ | Not yet | Not yet | Not yet | - -- \* Only available if natively supported by database. -- † Only supports JSON through SQL functions, but doesn't have a JSON column type. Therefore client JSON operations are not supported. -- ‡ JSON arrays are not yet supported: see the [CockroachDB connector page](/orm/overview/databases/cockroachdb) for details +| Feature | Supported | Prisma schema | Prisma Client | Prisma Migrate | +| --------------------------------- | :-------: | :--------------------------------------------------------------------------------: | :-----------: | :------------: | +| Autoincrementing IDs | ✔️ | [`autoincrement()`](/orm/prisma-schema/data-model/models#defining-a-default-value) | ✔️ | ✔️ | +| Arrays | PostgreSQL only | [`[]`](/orm/prisma-schema/data-model/models#type-modifiers) | ✔️ | ✔️ | +| Enums | ✔️\*† | [`enum`](/orm/prisma-schema/data-model/models#defining-enums) | ✔️ | ✔️ | +| Native database types | ✔️ | ✔️ | ✔️ | Not yet | +| SQL Views | ✔️ | Not yet | Not yet | Not yet | +| JSON support | ✔️† | ✔️ | ✔️ | ✔️ | +| Fuzzy/Phrase full text search | ✔️‡ | Not yet | Not yet | Not yet | +| Table inheritance | PostgreSQL and Microsoft SQL Server only | Not yet | ✔️ | Not yet | +| Authorization and user management | ✔️‡ | Not yet | Not yet | Not yet | + +- \* Not supported by Microsoft SQL Server +- † JSON and Enum types are supported in SQLite as of Prisma ORM 6.2.0. +- ‡ Not supported by SQLite ## NoSQL database features From 316c52e1636e9d752520d69bf50f53964c4fbd08 Mon Sep 17 00:00:00 2001 From: Jon Harrell <4829245+jharrell@users.noreply.github.com> Date: Fri, 3 Jan 2025 12:30:11 -0600 Subject: [PATCH 2/6] update omit preview feature info --- .../100-queries/063-excluding-fields.mdx | 10 +++---- .../050-prisma-client-reference.mdx | 14 ++-------- .../050-client-preview-features.mdx | 28 +++++++++---------- 3 files changed, 20 insertions(+), 32 deletions(-) diff --git a/content/200-orm/200-prisma-client/100-queries/063-excluding-fields.mdx b/content/200-orm/200-prisma-client/100-queries/063-excluding-fields.mdx index 71a586ad84..d1a0c9b12d 100644 --- a/content/200-orm/200-prisma-client/100-queries/063-excluding-fields.mdx +++ b/content/200-orm/200-prisma-client/100-queries/063-excluding-fields.mdx @@ -8,13 +8,13 @@ By default Prisma Client returns all fields from a model. You can use `select` t :::info -As of Prisma ORM 5.16.0, excluding fields globally and locally is supported via the `omitApi` Preview feature. +As of Prisma ORM 6.2.0, excluding fields globally and locally is supported. From versions 5.16.0 through 6.1.0, you must use the `omitApi` Preview feature. ::: ## Excluding a field globally using `omit` -The following is a type-safe way to exclude a field globally using the [`omitApi` Preview feature](/orm/reference/preview-features): +The following is a type-safe way to exclude a field globally: @@ -23,7 +23,6 @@ The following is a type-safe way to exclude a field globally using the [`omitApi ```prisma generator client { provider = "prisma-client-js" - previewFeatures = ["omitApi"] } model User { @@ -60,7 +59,7 @@ const user = await prisma.user.findUnique({ where: { id: 1 } }) ## Excluding a field locally using `omit` -The following is a type-safe way to exclude a field locally using the `omitApi` Preview feature: +The following is a type-safe way to exclude a field locally: @@ -69,7 +68,6 @@ The following is a type-safe way to exclude a field locally using the `omitApi` ```prisma generator client { provider = "prisma-client-js" - previewFeatures = ["omitApi"] } model User { @@ -180,7 +178,7 @@ Local omit (when an `omit` option is provided in a query) only applies to the qu :::note -The `omitApi` Preview feature, released in Prisma ORM 5.13.0, is the preferred way of omitting fields from a query result. The ability to globally omit fields was added to the `omitApi` Preview feature in Prisma ORM 5.16.0. This documentation is still relevant for versions of Prisma ORM prior to 5.13.0. +The `omitApi` feature, released in Preview in Prisma ORM 5.13.0 and Generally Available in Prisma ORM 6.2.0, is the preferred way of omitting fields from a query result. This documentation is still relevant for versions of Prisma ORM prior to 5.13.0. ::: 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 9c3755e365..7f2fce81e7 100644 --- a/content/200-orm/500-reference/050-prisma-client-reference.mdx +++ b/content/200-orm/500-reference/050-prisma-client-reference.mdx @@ -1932,24 +1932,14 @@ const usersWithCount = await prisma.user.findMany({ -### `omit` (Preview) +### `omit` `omit` defines which fields are excluded in the object that Prisma Client returns. -Because the `omit` option is currently in Preview, you need to enable it via the `omitApi` preview feature flag in your Prisma schema file: - -```prisma -generator client { - provider = "prisma-client-js" - previewFeatures = ["omitApi"] -} -``` - -After adding this flag, you need to run `prisma generate` again to re-generate Prisma Client. - #### Remarks - You cannot combine `omit` and `select` since they serve opposite purposes +- `omit` was released into General Availability with Prisma ORM 6.2.0. It was available via the `omitApi` [Preview feature](/orm/reference/preview-features/client-preview-features) in Prisma ORM versions `5.13.0` through `6.1.0`. #### Examples 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 bde9a0ac5e..bc2be4e0cd 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 @@ -26,7 +26,6 @@ The following [Preview](/orm/more/releases#preview) feature flags are available | `driverAdapters` | [5.4.0](https://github.com/prisma/prisma/releases/tag/5.4.0) | [Submit feedback](https://github.com/prisma/prisma/issues/3108) | | `relationJoins` | [5.7.0](https://github.com/prisma/prisma/releases/tag/5.7.0) | [Submit feedback](https://github.com/prisma/prisma/discussions/22288) | | `nativeDistinct` | [5.7.0](https://github.com/prisma/prisma/releases/tag/5.7.0) | [Submit feedback](https://github.com/prisma/prisma/discussions/22287) | -| `omitApi` | [5.13.0](https://github.com/prisma/prisma/releases/tag/5.13.0) | [Submit feedback](https://github.com/prisma/prisma/discussions/23924) | | `prismaSchemaFolder` | [5.15.0](https://github.com/prisma/prisma/releases/tag/5.15.0) | [Submit feedback](https://github.com/prisma/prisma/discussions/24413) | | `typedSql` | [5.19.0](https://github.com/prisma/prisma/releases/tag/5.19.0) | [Submit feedback](https://github.com/prisma/prisma/discussions/25106) | | `strictUndefinedChecks` | [5.20.0](https://github.com/prisma/prisma/releases/tag/5.20.0) | [Submit feedback](https://github.com/prisma/prisma/discussions/25271) | @@ -59,19 +58,20 @@ 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) | -| [`tracing`](/orm/prisma-client/observability-and-logging/opentelemetry-tracing) | [4.2.0](https://github.com/prisma/prisma/releases/tag/4.2.0) | [6.1.0](https://github.com/prisma/prisma/releases/tag/6.1.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) | | -| [`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-simple) | [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) | +| Feature | Released into Preview | Released into General Availability | +| ------------------- | :------------------------------------------------------------- | :--------------------------------- | +| `omitApi` | [5.13.0](https://github.com/prisma/prisma/releases/tag/5.13.0) | [6.2.0](https://github.com/prisma/prisma/releases/tag/6.2.0) | +| `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) | +| [`tracing`](/orm/prisma-client/observability-and-logging/opentelemetry-tracing) | [4.2.0](https://github.com/prisma/prisma/releases/tag/4.2.0) | [6.1.0](https://github.com/prisma/prisma/releases/tag/6.1.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) | | +| [`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-simple) | [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/using-raw-sql/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.14.0](https://github.com/prisma/prisma/releases/tag/3.14.0) | | [`mongodb`](/orm/overview/databases/mongodb) | | [3.12.0](https://github.com/prisma/prisma/releases/tag/3.12.0) | From 4775c04b64997c23967be6958f6c029b44a4a697 Mon Sep 17 00:00:00 2001 From: Jon Harrell <4829245+jharrell@users.noreply.github.com> Date: Fri, 3 Jan 2025 16:47:25 -0600 Subject: [PATCH 3/6] fix anchors --- .../100-queries/035-select-fields.mdx | 2 +- .../300-client-extensions/130-result.mdx | 2 +- .../500-reference/050-prisma-client-reference.mdx | 10 +++++----- 3 files changed, 7 insertions(+), 7 deletions(-) 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 e9a3aebea0..00f27fbd1b 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 @@ -64,7 +64,7 @@ const users = await prisma.user.findFirst() If you want to customize the result and have a different combination of fields returned, you can: - Use [`select`](/orm/reference/prisma-client-reference#select) to return specific fields. You can also use a [nested `select`](/orm/prisma-client/queries/relation-queries#select-specific-fields-of-included-relations) by selecting relation fields. -- Use [`omit`](/orm/reference/prisma-client-reference#omit-preview) to exclude specific fields from the result. `omit` can be seen as the "opposite" to `select`. +- Use [`omit`](/orm/reference/prisma-client-reference#omit) to exclude specific fields from the result. `omit` can be seen as the "opposite" to `select`. - Use [`include`](/orm/reference/prisma-client-reference#include) to additionally [include relations](/orm/prisma-client/queries/relation-queries#nested-reads). In all cases, the query result will be statically typed, ensuring that you don't accidentally access any fields that you did not actually query from the database. diff --git a/content/200-orm/200-prisma-client/300-client-extensions/130-result.mdx b/content/200-orm/200-prisma-client/300-client-extensions/130-result.mdx index 04543b1989..a413790ec3 100644 --- a/content/200-orm/200-prisma-client/300-client-extensions/130-result.mdx +++ b/content/200-orm/200-prisma-client/300-client-extensions/130-result.mdx @@ -143,7 +143,7 @@ await user.save() ## Using `omit` query option with `result` extension component -You can use the [`omit` (Preview) option](/orm/reference/prisma-client-reference#omit-preview) with [custom fields](#add-a-custom-field-to-query-results) and fields needed by custom fields. +You can use the [`omit` (Preview) option](/orm/reference/prisma-client-reference#omit) with [custom fields](#add-a-custom-field-to-query-results) and fields needed by custom fields. ### `omit` fields needed by custom fields from query result 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 7f2fce81e7..2c462acadc 100644 --- a/content/200-orm/500-reference/050-prisma-client-reference.mdx +++ b/content/200-orm/500-reference/050-prisma-client-reference.mdx @@ -792,7 +792,7 @@ const user = await prisma.user.findMany({ | `data` | `XOR`UserUncheckedCreateInput>` | **Yes** | Wraps all the model fields in a type so that they can be provided when creating new records. It also includes relation fields which lets you perform (transactional) nested inserts. Fields that are marked as optional or have default values in the datamodel are optional. | | [`select`](#select) | `XOR` | No | [Specifies which properties to include](/orm/prisma-client/queries/select-fields) on the returned object. | | [`include`](#include) | `XOR` | No | [Specifies which relations should be eagerly loaded](/orm/prisma-client/queries/relation-queries) on the returned object. | -| [`omit`](#omit-preview) | `XOR` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0 | +| [`omit`](#omit) | `XOR` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0 | | `relationLoadStrategy` | `'join'` or `'query'` | No | **Default: `join`**. Specifies the [load strategy](/orm/prisma-client/queries/relation-queries#relation-load-strategies-preview) for a relation query. Only available in combination with `include` (or `select` on a relation field). In [Preview](/orm/more/releases#preview) since 5.9.0. | #### Return type @@ -899,7 +899,7 @@ prisma:query COMMIT | `where` | `UserWhereUniqueInput` | **Yes** | Wraps all fields of a model so that a record can be selected ([learn more](#filter-on-non-unique-fields-with-userwhereuniqueinput)).

Before version 4.5.0, this type only wraps _unique_ fields of a model. | | [`select`](#select) | `XOR` | No | [Specifies which properties to include](/orm/prisma-client/queries/select-fields) on the returned object. | | [`include`](#include) | `XOR` | No | [Specifies which relations should be eagerly loaded](/orm/prisma-client/queries/relation-queries) on the returned object. | -| [`omit`](#omit-preview) | `XOR` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0. | +| [`omit`](#omit) | `XOR` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0. | | `relationLoadStrategy` | `'join'` or `'query'` | No | **Default: `join`**. Specifies the [load strategy](/orm/prisma-client/queries/relation-queries#relation-load-strategies-preview) for a relation query. Only available in combination with `include` (or `select` on a relation field). In [Preview](/orm/more/releases#preview) since 5.9.0. | #### Return type @@ -948,7 +948,7 @@ This section covers the usage of the `upsert()` operation. To learn about using | `where` | `UserWhereUniqueInput` | **Yes** | Wraps all fields of a model so that a record can be selected ([learn more](#filter-on-non-unique-fields-with-userwhereuniqueinput)).

Before version 4.5.0, this type only wraps _unique_ fields of a model. | | [`select`](#select) | `XOR` | No | [Specifies which properties to include](/orm/prisma-client/queries/select-fields) on the returned object. | | [`include`](#include) | `XOR` | No | [Specifies which relations should be eagerly loaded](/orm/prisma-client/queries/relation-queries) on the returned object. | -| [`omit`](#omit-preview) | `XOR` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0 | +| [`omit`](#omit) | `XOR` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0 | | `relationLoadStrategy` | `'join'` or `'query'` | No | **Default: `join`**. Specifies the [load strategy](/orm/prisma-client/queries/relation-queries#relation-load-strategies-preview) for a relation query. Only available in combination with `include` (or `select` on a relation field). In [Preview](/orm/more/releases#preview) since 5.9.0. | #### Return type @@ -1154,7 +1154,7 @@ To delete records that match a certain criteria, use [`deleteMany`](#deletemany) | `where` | `UserWhereUniqueInput` | **Yes** | Wraps all fields of a model so that a record can be selected ([learn more](#filter-on-non-unique-fields-with-userwhereuniqueinput)).

Before version 4.5.0, this type only wraps _unique_ fields of a model. | | [`select`](#select) | `XOR` | No | [Specifies which properties to include](/orm/prisma-client/queries/select-fields) on the returned object. | | [`include`](#include) | `XOR` | No | [Specifies which relations should be eagerly loaded](/orm/prisma-client/queries/relation-queries) on the returned object. | -| [`omit`](#omit-preview) | `XOR` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0 | +| [`omit`](#omit) | `XOR` | No | Specifies which properties to exclude on the returned object. In [Preview](/orm/more/releases#preview) since 5.13.0 | | `relationLoadStrategy` | `'join'` or `'query'` | No | **Default: `join`**. Specifies the [load strategy](/orm/prisma-client/queries/relation-queries#relation-load-strategies-preview) for a relation query. Only available in combination with `include` (or `select` on a relation field). In [Preview](/orm/more/releases#preview) since 5.9.0. | #### Return type @@ -1265,7 +1265,7 @@ const users = await prisma.user.createMany({ | ----------------- | --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data` | `Enumerable` | **Yes** | Wraps all the model fields in a type so that they can be provided when creating new records. Fields that are marked as optional or have default values in the datamodel are optional. | | [`select`](#select) | `XOR` | No | [Specifies which properties to include](/orm/prisma-client/queries/select-fields) on the returned objects. | -| [`omit`](#omit-preview) | `XOR` | No | Specifies which properties to exclude on the returned objects. In [Preview](/orm/more/releases#preview) since 5.13.0. Mutually exclusive with `select`. | +| [`omit`](#omit) | `XOR` | No | Specifies which properties to exclude on the returned objects. In [Preview](/orm/more/releases#preview) since 5.13.0. Mutually exclusive with `select`. | | [`include`](#include) | `XOR` | No | [Specifies which relations should be eagerly loaded](/orm/prisma-client/queries/relation-queries) on the returned objects. | | `skipDuplicates?` | `boolean` | No | Do not insert records with unique fields or ID fields that already exist. Only supported by databases that support [`ON CONFLICT DO NOTHING`](https://www.postgresql.org/docs/9.5/sql-insert.html#SQL-ON-CONFLICT). This excludes MongoDB and SQLServer | From 20b3d925f4bbffbfad4e7b243ff90fcc59304e88 Mon Sep 17 00:00:00 2001 From: Nikolas Burk Date: Mon, 6 Jan 2025 16:30:22 -0600 Subject: [PATCH 4/6] update type mappping for sqlite --- .../050-overview/500-databases/500-sqlite.mdx | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/content/200-orm/050-overview/500-databases/500-sqlite.mdx b/content/200-orm/050-overview/500-databases/500-sqlite.mdx index 0957f1b5d3..769dd938df 100644 --- a/content/200-orm/050-overview/500-databases/500-sqlite.mdx +++ b/content/200-orm/050-overview/500-databases/500-sqlite.mdx @@ -5,19 +5,15 @@ metaDescription: 'This page explains how Prisma can connect to a SQLite database tocDepth: 3 --- - - The SQLite data source connector connects Prisma ORM to a [SQLite](https://www.sqlite.org/) database file. These files always have the file ending `.db` (e.g.: `dev.db`). By default, the SQLite 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. - - ## Example To connect to a SQLite database file, you need to configure a [`datasource`](/orm/prisma-schema/overview/data-sources) block in your [Prisma schema](/orm/prisma-schema): -```prisma file=schema.prisma showLineNumbers +```prisma file=schema.prisma datasource db { provider = "sqlite" url = "file:./dev.db" @@ -46,11 +42,18 @@ The SQLite connector maps the [scalar types](/orm/prisma-schema/data-model/model | `Float` | `REAL` | | `Decimal` | `DECIMAL` | | `DateTime` | `NUMERIC` | -| `Json` | \* | -| `Enum` | \* | +| `Json` | `JSONB` | | `Bytes` | `BLOB` | +| `Enum` | `TEXT` | + +:::warning + +When using `enum` fields in SQLite, be aware of the following: + +- **No database-level enforcement for correctness**: If you bypass Prisma ORM and store an invalid enum entry in the database, Prisma Client queries will fail at runtime when reading that entry. +- **No migration-level enforcement for correctness**: It's possible to end up with incorrect data after schema changes similarly to MongoDB (since the enums aren't checked by the database). -> \* As SQLite does not have native `JSON` or `ENUM` types, these are implemented via shims and consistency is maintained by Prisma ORM. +::: ## Rounding errors on big numbers From 0e7778caa5eec0117e1b5dac3612c6efa828e3be Mon Sep 17 00:00:00 2001 From: Nikolas Burk Date: Mon, 6 Jan 2025 16:42:30 -0600 Subject: [PATCH 5/6] update section about omit api --- .../100-queries/063-excluding-fields.mdx | 132 +++++------------- 1 file changed, 34 insertions(+), 98 deletions(-) diff --git a/content/200-orm/200-prisma-client/100-queries/063-excluding-fields.mdx b/content/200-orm/200-prisma-client/100-queries/063-excluding-fields.mdx index d1a0c9b12d..3ba0c19adb 100644 --- a/content/200-orm/200-prisma-client/100-queries/063-excluding-fields.mdx +++ b/content/200-orm/200-prisma-client/100-queries/063-excluding-fields.mdx @@ -4,43 +4,23 @@ metaTitle: 'Excluding fields' metaDescription: 'This page explains how to exclude sensitive fields from Prisma Client' --- -By default Prisma Client returns all fields from a model. You can use `select` to narrow the result set, but that can be unwieldy if you have a large model and you only want to exclude one or two fields. +By default Prisma Client returns all fields from a model. You can use [`select`](/orm/prisma-client/queries/select-fields) to narrow the result set, but that can be unwieldy if you have a large model and you only want to exclude a small number of fields. :::info -As of Prisma ORM 6.2.0, excluding fields globally and locally is supported. From versions 5.16.0 through 6.1.0, you must use the `omitApi` Preview feature. +As of Prisma ORM 6.2.0, excluding fields is supported via the `omit` option that you can pass to Prisma Client. From versions 5.16.0 through 6.1.0, you must use the `omitApi` Preview feature to access this option. ::: ## Excluding a field globally using `omit` -The following is a type-safe way to exclude a field globally: +The following is a type-safe way to exclude a field _globally_ (i.e. for _all_ queries against a given model): - - -```prisma -generator client { - provider = "prisma-client-js" -} - -model User { - id Int @id @default(autoincrement()) - firstName String - lastName String - email String @unique - password String - createdAt DateTime @default(now()) - updatedAt DateTime @updatedAt -} -``` - - - -```tsx +```ts const prisma = new PrismaClient({ omit: { user: { @@ -55,37 +35,33 @@ const user = await prisma.user.findUnique({ where: { id: 1 } }) - - -## Excluding a field locally using `omit` - -The following is a type-safe way to exclude a field locally: - - - ```prisma -generator client { - provider = "prisma-client-js" -} - model User { id Int @id @default(autoincrement()) + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt firstName String lastName String email String @unique password String - createdAt DateTime @default(now()) - updatedAt DateTime @updatedAt } ``` + + +## Excluding a field locally using `omit` + +The following is a type-safe way to exclude a field _locally_ (i.e. for an _individual_ query): + + + -```tsx +```ts const prisma = new PrismaClient() // The password field is excluded only in this query @@ -101,6 +77,23 @@ const user = await prisma.user.findUnique({ + + + +```prisma +model User { + id Int @id @default(autoincrement()) + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + firstName String + lastName String + email String @unique + password String +} +``` + + + ## How to omit multiple fields @@ -169,64 +162,7 @@ const user = await prisma.user.findUnique({ It's important to understand when to omit a field globally or locally: -- If you are omitting a field in order to prevent it from accidentally being included in a query, it's best to omit it globally. For example: Globally omitting the password field from a User model so that sensitive information doesn't accidentally get exposed. -- If you are omitting a field because it's not needed in a query, it's best to omit it locally. +- If you are omitting a field in order to prevent it from accidentally being included in a query, it's best to omit it _globally_. For example: Globally omitting the `password` field from a `User` model so that sensitive information doesn't accidentally get exposed. +- If you are omitting a field because it's not needed in a query, it's best to omit it _locally_. Local omit (when an `omit` option is provided in a query) only applies to the query it is defined in, while a global omit applies to every query made with the same Prisma Client instance, [unless a specific select is used or the omit is overridden](#how-to-select-a-previously-omitted-field). - -## Excluding the password field without using `omit` - -:::note - -The `omitApi` feature, released in Preview in Prisma ORM 5.13.0 and Generally Available in Prisma ORM 6.2.0, is the preferred way of omitting fields from a query result. This documentation is still relevant for versions of Prisma ORM prior to 5.13.0. - -::: - -The following is a type-safe `exclude` function returns a user without the `password` field. - - - - - -```tsx -// Exclude keys from user -function exclude( - user: User, - keys: Key[] -): Omit { - return Object.fromEntries( - Object.entries(user).filter(([key]) => !keys.includes(key)) - ) -} - -function main() { - const user = await prisma.user.findUnique({ where: 1 }) - const userWithoutPassword = exclude(user, ['password']) -} -``` - - - - - -```js -// Exclude keys from user -function exclude(user, keys) { - return Object.fromEntries( - Object.entries(user).filter(([key]) => !keys.includes(key)) - ); -} - -function main() { - const user = await prisma.user.findUnique({ where: 1 }) - const userWithoutPassword = exclude(user, ['password']) -} -``` - - - - - -In the TypeScript example, we've provided two generics: `User` and `Key`. The `Key` generic is defined as the keys of a `User` (e.g. `email`, `password`, `firstName`, etc.). - -These generics flow through the logic, returning a `User` that omits the list of `Key`s provided. From feabb19aaa985f60c4571a4be8af9341bddb7ace Mon Sep 17 00:00:00 2001 From: Nikolas Burk Date: Mon, 6 Jan 2025 16:44:08 -0600 Subject: [PATCH 6/6] update section about omit api --- .../200-prisma-client/100-queries/063-excluding-fields.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/200-orm/200-prisma-client/100-queries/063-excluding-fields.mdx b/content/200-orm/200-prisma-client/100-queries/063-excluding-fields.mdx index 3ba0c19adb..1da83bd1c0 100644 --- a/content/200-orm/200-prisma-client/100-queries/063-excluding-fields.mdx +++ b/content/200-orm/200-prisma-client/100-queries/063-excluding-fields.mdx @@ -55,7 +55,7 @@ model User { ## Excluding a field locally using `omit` -The following is a type-safe way to exclude a field _locally_ (i.e. for an _individual_ query): +The following is a type-safe way to exclude a field _locally_ (i.e. for a _single_ query):