Update documentation for ORM 6.2 (#6567)

* 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). * update omit preview feature info * fix anchors * update type mappping for sqlite * update section about omit api * update section about omit api --------- Co-authored-by: Nikolas Burk <[email protected]>
prisma · Jan 7, 2025 · fdd3734 · fdd3734
1 parent 12218a0
commit fdd3734
Show file tree

Hide file tree

Showing 9 changed files with 125 additions and 203 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
@@ -5,19 +5,15 @@ metaDescription: 'This page explains how Prisma can connect to a SQLite database
 tocDepth: 3
 ---
 
-<TopBlock>
-
 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.
 
-</TopBlock>
-
 ## 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,8 +42,18 @@ The SQLite connector maps the [scalar types](/orm/prisma-schema/data-model/model
 | `Float`    | `REAL`        |
 | `Decimal`  | `DECIMAL`     |
 | `DateTime` | `NUMERIC`     |
-| `Json`     | Not supported |
+| `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).
+
+:::
 
 ## Rounding errors on big numbers
 

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
@@ -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/100-queries/063-excluding-fields.mdx b/content/200-orm/200-prisma-client/100-queries/063-excluding-fields.mdx
@@ -4,44 +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 5.16.0, excluding fields globally and locally is supported via 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 using the [`omitApi` Preview feature](/orm/reference/preview-features):
+The following is a type-safe way to exclude a field _globally_ (i.e. for _all_ queries against a given model):
 
 <TabbedContent code>
 
-<TabItem value="Schema">
-
-```prisma
-generator client {
-  provider        = "prisma-client-js"
-  previewFeatures = ["omitApi"]
-}
-
-model User {
-  id        Int      @id @default(autoincrement())
-  firstName String
-  lastName  String
-  email     String   @unique
-  password  String
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-}
-```
-
-</TabItem>
-
 <TabItem value="Code">
 
-```tsx
+```ts
 const prisma = new PrismaClient({
   omit: {
     user: {
@@ -56,38 +35,33 @@ const user = await prisma.user.findUnique({ where: { id: 1 } })
 
 </TabItem>
 
-</TabbedContent>
-
-## Excluding a field locally using `omit`
-
-The following is a type-safe way to exclude a field locally using the `omitApi` Preview feature:
-
-<TabbedContent code>
-
 <TabItem value="Schema">
 
 ```prisma
-generator client {
-  provider        = "prisma-client-js"
-  previewFeatures = ["omitApi"]
-}
-
 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
 }
 ```
 
 </TabItem>
 
+</TabbedContent>
+
+## Excluding a field locally using `omit`
+
+The following is a type-safe way to exclude a field _locally_ (i.e. for a _single_ query):
+
+<TabbedContent code>
+
 <TabItem value="Code">
 
-```tsx
+```ts
 const prisma = new PrismaClient()
 
 // The password field is excluded only in this query
@@ -103,6 +77,23 @@ const user = await prisma.user.findUnique({
 
 </TabItem>
 
+
+<TabItem value="Schema">
+
+```prisma
+model User {
+  id        Int      @id @default(autoincrement())
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  firstName String
+  lastName  String
+  email     String   @unique
+  password  String
+}
+```
+
+</TabItem>
+
 </TabbedContent>
 
 ## How to omit multiple fields
@@ -171,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` 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 following is a type-safe `exclude` function returns a user without the `password` field.
-
-<TabbedContent code>
-
-<TabItem value="TypeScript">
-
-```tsx
-// Exclude keys from user
-function exclude<User, Key extends keyof User>(
-  user: User,
-  keys: Key[]
-): Omit<User, Key> {
-  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'])
-}
-```
-
-</TabItem>
-
-<TabItem value="JavaScript">
-
-```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'])
-}
-```
-
-</TabItem>
-
-</TabbedContent>
-
-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.
diff --git a/...200-prisma-client/200-special-fields-and-types/100-working-with-json-fields.mdx b/...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
 ---
 
-<TopBlock>
-
 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
 ```
 
-</TopBlock>
-
 ## 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/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